v3.0.0

.readthedocs.yml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "3.13"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

docs/_templates/globaltoc.html

@@ -12,6 +12,7 @@ <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
   <li><a href="{{ pathto('api/languages') }}">Languages</a></li>
   <li><a href="{{ pathto('api/orders') }}">Orders</a></li>
   <li><a href="{{ pathto('api/payment_cards') }}">Payment cards</a></li>
+  <li><a href="{{ pathto('api/permission_templates') }}">Permission templates</a></li>
   <li><a href="{{ pathto('api/projects') }}">Projects</a></li>
   <li><a href="{{ pathto('api/queued_processes') }}">Queued processes</a></li>
   <li><a href="{{ pathto('api/screenshots') }}">Screenshots</a></li>

docs/additional_info/changelog.rst

@@ -6,7 +6,35 @@ Changelog
 3.0.0 (15-Oct-2024)
 -------------------
 
-* Drop support for Python 3.8 (EOL)
+* Drop support for Python 3.8 (EOL), test with Python 3.13
+* Added support for `PermissionTemplates` endpoint:
+
+.. code-block:: python
+
+  templates = client.permission_templates(TEAM_ID)
+  
+  template.id # => 1
+  template.role # => "Manager"
+  template.permissions # => ['branches_main_modify', ...]
+  template.description # => 'Manage project settings ...'
+  template.tag # => 'Full access'
+  template.tagColor # => 'green'
+  template.tagInfo # => ''
+  template.doesEnableAllReadOnlyLanguages # => true
+
+* Added `role_id` to the `Contributor` model
+
+.. code-block:: python
+
+  contributor = client.contributor(PROJECT_ID, CONTRIBUTOR_ID)
+  contributor.role_id # => 5
+
+* Added `role_id` to the `TeamUserGroup` model
+
+.. code-block:: python
+
+  group = client.team_user_group(TEAM_ID, GROUP_ID)
+  group.role_id # => 5
 
 2.3.0 (15-May-2024)
 -------------------

docs/api/permission_templates.rst

@@ -0,0 +1,27 @@
+Permission templates endpoint
+=============================
+
+`Permission templates documentation <https://developers.lokalise.com/reference/list-all-permission-templates>`_
+
+Fetch all permission templates
+------------------------------
+
+.. py:function:: permission_templates(team_id)
+
+  :param team_id: ID of the team
+  :type team_id: str or int
+
+Example:
+
+.. code-block:: python
+
+  templates = client.permission_templates(12345)
+  
+  template.id # => 1
+  template.role # => "Manager"
+  template.permissions # => ['branches_main_modify', ...]
+  template.description # => 'Manage project settings ...'
+  template.tag # => 'Full access'
+  template.tagColor # => 'green'
+  template.tagInfo # => ''
+  template.doesEnableAllReadOnlyLanguages # => true

docs/index.rst

@@ -52,6 +52,7 @@ Usage
    api/languages
    api/orders
    api/payment_cards
+   api/permission_templates
    api/projects
    api/queued_processes
    api/snapshots

lokalise/client.py

@@ -15,6 +15,7 @@
 from .collections.languages import LanguagesCollection
 from .collections.orders import OrdersCollection
 from .collections.payment_cards import PaymentCardsCollection
+from .collections.permission_templates import PermissionTemplatesCollection
 from .collections.projects import ProjectsCollection
 from .collections.queued_processes import QueuedProcessesCollection
 from .collections.snapshots import SnapshotsCollection
@@ -685,6 +686,18 @@ def delete_payment_card(self, payment_card_id: Union[str, int]) -> Dict:
             delete(parent_id=payment_card_id)
         return resp
 
+    def permission_templates(
+            self, team_id: Union[int, str]) -> PermissionTemplatesCollection:
+        """Fetches all permission templates for the given team.
+
+        :param team_id: ID of the team
+        :type team_id: int or str
+        :return: Collection of permission templates
+        """
+        raw_templates = self.get_endpoint("permission_templates"). \
+            all(parent_id=team_id)
+        return PermissionTemplatesCollection(raw_templates)
+
     def projects(self, params: Optional[Dict] = None) -> ProjectsCollection:
         """Fetches all projects available to the currently authorized user
         (identified by the API token).
@@ -916,7 +929,7 @@ def segments(self, project_id: str, key_id: Union[str, int], lang_iso: str,
             subresource_id=lang_iso)
         return SegmentsCollection(raw_segments)
 
-    # pylint: disable=too-many-arguments
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
     def segment(self,
                 project_id: str,
                 key_id: Union[str, int],
@@ -964,7 +977,7 @@ def update_segment(self,
             resource_id=key_id,
             subresource_id=f"{lang_iso}/{segment_number}")
         return SegmentModel(raw_segment)
-    # pylint: enable=too-many-arguments
+    # pylint: enable=too-many-arguments,too-many-positional-arguments
 
     def tasks(self, project_id: str,
               params: Optional[Dict] = None) -> TasksCollection:

lokalise/collections/permission_templates.py

@@ -0,0 +1,15 @@
+"""
+lokalise.collections.permission_templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Module containing permission templates collection.
+"""
+
+from .base_collection import BaseCollection
+from ..models.permission_template import PermissionTemplateModel
+
+
+class PermissionTemplatesCollection(BaseCollection):
+    """Describes permission templates.
+    """
+    DATA_KEY = "roles"
+    MODEL_KLASS = PermissionTemplateModel

lokalise/endpoints/permission_templates_endpoint.py

@@ -0,0 +1,12 @@
+"""
+lokalise.endpoints.permission_templates_endpoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Module containing permission templates endpoint.
+"""
+from .base_endpoint import BaseEndpoint
+
+
+class PermissionTemplatesEndpoint(BaseEndpoint):
+    """Describes permission templates endpoint.
+    """
+    PATH = "teams/$parent_id/roles"

lokalise/models/contributor.py

@@ -22,4 +22,5 @@ class ContributorModel(BaseModel):
         "is_reviewer",
         "languages",
         "admin_rights",
+        "role_id",
     ]

lokalise/models/permission_template.py

@@ -0,0 +1,23 @@
+"""
+lokalise.models.permission_template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Module containing permission template.
+"""
+
+from .base_model import BaseModel
+
+
+class PermissionTemplateModel(BaseModel):
+    """Describes permission template.
+    """
+
+    ATTRS = [
+        'id',
+        'role',
+        'permissions',
+        'description',
+        'tag',
+        'tagColor',
+        'tagInfo',
+        'doesEnableAllReadOnlyLanguages',
+    ]

lokalise/models/team_user_group.py

@@ -19,5 +19,6 @@ class TeamUserGroupModel(BaseModel):
         'created_at_timestamp',
         'team_id',
         'projects',
-        'members'
+        'members',
+        "role_id",
     ]

tests/cassettes/contributors_test/test_contributor.yaml

@@ -20,7 +20,7 @@ interactions:
         B","created_at":"2018-08-21 15:35:25 (Etc\/UTC)","created_at_timestamp":1534865725,"is_admin":true,"is_reviewer":true,"languages":[{"lang_id":10052,"lang_iso":"que","lang_name":"Quenya","is_writable":true},{"lang_id":640,"lang_iso":"en","lang_name":"English","is_writable":true},{"lang_id":611,"lang_iso":"en_AU","lang_name":"English
         (Australia)","is_writable":true},{"lang_id":672,"lang_iso":"de_DE","lang_name":"German
         (Germany)","is_writable":true},{"lang_id":10153,"lang_iso":"lv","lang_name":"Latvian","is_writable":true},{"lang_id":600,"lang_iso":"ru_RU","lang_name":"Russian
-        (Russia)","is_writable":true}],"admin_rights":["upload","download","tasks","contributors","screenshots","keys","languages","settings","activity","statistics"]}}'
+        (Russia)","is_writable":true}],"admin_rights":["upload","download","tasks","contributors","screenshots","keys","languages","settings","activity","statistics"],"role_id":5}}'
     headers:
       Access-Control-Allow-Headers:
       - Content-Type

tests/cassettes/permission_templates_test/test_permission_templates.yaml

@@ -0,0 +1,75 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - application/json
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-lokalise-api plugin/2.1.1
+      x-api-token:
+      - FILTERED
+    method: GET
+    uri: https://api.lokalise.com/api2/teams/176692/roles
+  response:
+    body:
+      string: '{"roles":[{"id":1,"role":"Manager","permissions":["activity","branches_main_modify","branches_create","branches_merge","statistics","tasks","contributors","settings","manage_languages","download","upload","glossary_delete","glossary_edit","manage_keys","screenshots","review","custom_status_modify"],"description":"Manage
+        project settings, contributors and tasks","tag":"Full access","tagColor":"green","tagInfo":null,"doesEnableAllReadOnlyLanguages":true},{"id":2,"role":"Developer","permissions":["activity","branches_main_modify","branches_create","download","upload","manage_keys","screenshots"],"description":"Create
+        keys, upload and download content","tag":"Advanced","tagColor":"cyan","tagInfo":null,"doesEnableAllReadOnlyLanguages":true},{"id":3,"role":"Content
+        creator","permissions":["activity","manage_keys","manage_languages","screenshots","branches_main_modify"],"description":"Create,
+        translate and edit keys, manage screenshots","tag":"Advanced","tagColor":"cyan","tagInfo":null,"doesEnableAllReadOnlyLanguages":true},{"id":4,"role":"Reviewer","permissions":["branches_main_modify","review","custom_status_modify"],"description":"Translate
+        keys, control key statuses","tag":"Basic","tagColor":"grey","tagInfo":"All
+        users, regardless of their assigned roles and permissions, are granted entry-level
+        access, such as: View glossary, View source content, Collaborate via comments,
+        Limited access to editor, Generate API tokens","doesEnableAllReadOnlyLanguages":false},{"id":5,"role":"Translator","permissions":["branches_main_modify"],"description":"Translate
+        keys","tag":"Basic","tagColor":"grey","tagInfo":"All users, regardless of
+        their assigned roles and permissions, are granted entry-level access, such
+        as: View glossary, View source content, Collaborate via comments, Limited
+        access to editor, Generate API tokens","doesEnableAllReadOnlyLanguages":false}]}'
+    headers:
+      Cache-Control:
+      - max-age=-172800, must-revalidate, no-cache, no-store, private
+      Connection:
+      - keep-alive
+      Content-Type:
+      - application/json
+      Date:
+      - Tue, 15 Oct 2024 16:26:21 GMT
+      Expires:
+      - Thu, 17 Oct 2024 16:26:21 GMT
+      Referrer-Policy:
+      - origin
+      Server:
+      - nginx
+      Set-Cookie:
+      - PHPSESSID=deleted; expires=Mon, 16-Oct-2023 16:26:20 GMT; Max-Age=0; path=/;
+        httponly
+      Strict-Transport-Security:
+      - max-age=31536000
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Accept-Encoding
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - deny
+      X-Lokalise-Process-Id:
+      - aa5c55d8-3117-40a6-bbba-d781e1ee9dcf
+      X-Pagination-Limit:
+      - '5'
+      X-Pagination-Page:
+      - '1'
+      X-Pagination-Page-Count:
+      - '1'
+      X-Pagination-Total-Count:
+      - '5'
+      X-XSS-Protection:
+      - 1; mode=block
+      pragma:
+      - no-cache
+    status:
+      code: 200
+      message: OK
+version: 1

tests/cassettes/team_user_groups_test/test_team_user_group.yaml

@@ -17,7 +17,7 @@ interactions:
   response:
     body:
       string: '{"group_id":515,"name":"Demo","permissions":{"is_admin":true,"is_reviewer":false,"admin_rights":["upload","download","tasks","contributors","screenshots","keys","languages","settings","activity","statistics"],"languages":[]},"created_at":"2019-03-19
-        19:53:04 (Etc\/UTC)","created_at_timestamp":1553025184,"team_id":176692,"projects":["531138705d0ba0c18f5b43.63503311","803826145ba90b42d5d860.46800099"],"members":[20181,25753]}'
+        19:53:04 (Etc\/UTC)","created_at_timestamp":1553025184,"team_id":176692,"projects":["531138705d0ba0c18f5b43.63503311","803826145ba90b42d5d860.46800099"],"members":[20181,25753],"role_id":5}'
     headers:
       Access-Control-Allow-Headers:
       - Content-Type

tests/client/contributors_test.py

@@ -51,6 +51,7 @@ def test_contributor(client):
     assert contributor.is_reviewer
     assert contributor.languages[0]["lang_id"] == 10052
     assert contributor.admin_rights[0] == "upload"
+    assert contributor.role_id == 5
 
 
 @pytest.mark.vcr

tests/client/keys_test.py

@@ -33,6 +33,7 @@ def test_keys(client):
     assert not keys.has_next_cursor()
     assert keys.next_cursor is None
 
+
 @pytest.mark.vcr
 def test_keys_cursor(client):
     """Tests fetching of keys with cursor
@@ -55,6 +56,7 @@ def test_keys_cursor(client):
     assert not keys.has_next_page()
     assert not keys.has_prev_page()
 
+
 @pytest.mark.vcr
 def test_create_keys(client):
     """Tests creation of translation keys

tests/client/permission_templates_test.py

@@ -0,0 +1,26 @@
+"""
+Tests for the PermissionTemplates endpoint.
+"""
+
+import pytest
+
+
+TEAM_ID = 176692
+
+
+@pytest.mark.vcr
+def test_permission_templates(client):
+    """Tests fetching of all permission templates
+    """
+    templates = client.permission_templates(TEAM_ID)
+
+    template = templates.items[0]
+
+    assert template.id == 1
+    assert template.role == 'Manager'
+    assert 'branches_main_modify' in template.permissions
+    assert template.description == 'Manage project settings, contributors and tasks'
+    assert template.tag == 'Full access'
+    assert template.tagColor == 'green'
+    assert template.tagInfo is None
+    assert template.doesEnableAllReadOnlyLanguages is True

tests/client/team_user_groups_test.py

@@ -54,6 +54,7 @@ def test_team_user_group(client):
     assert group.team_id == 176692
     assert "531138705d0ba0c18f5b43.63503311" in group.projects
     assert 20181 in group.members
+    assert group.role_id == 5
 
 
 @pytest.mark.vcr

tests/client/translations_test.py

@@ -44,6 +44,7 @@ def test_translations_pagination(client):
     assert translations.has_next_page()
     assert translations.has_prev_page()
 
+
 @pytest.mark.vcr
 def test_translations_pagination_cursor(client):
     """Tests fetching of all translations with pagination and cursor
@@ -65,6 +66,7 @@ def test_translations_pagination_cursor(client):
 
     assert translations.has_next_cursor()
 
+
 @pytest.mark.vcr
 def test_translation(client):
     """Tests fetching of a translation