Contentstack 2.7.0__tar.gz → 2.8.0__tar.gz

{contentstack-2.7.0 → contentstack-2.8.0}/Contentstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Contentstack
-Version: 2.7.0
+Version: 2.8.0
 Summary: Contentstack is a headless CMS with an API-first approach.
 Home-page: https://github.com/contentstack/contentstack-python
 Author: Contentstack
@@ -162,6 +162,36 @@ image = stack.image_transform(url, {'width': 100, 'height': 100}).get_url()
 image = stack.image_transform(url, {'auto': 'webp'}).get_url()
 ```
 
+### Working with Taxonomies
+
+Taxonomies published to an environment/locale can be fetched directly via the Content Delivery API.
+
+```python
+# List all published taxonomies
+result = stack.taxonomy().limit(10).include_count().find()
+taxonomies = result['taxonomies']
+
+# Fetch a single taxonomy, with locale fallback
+taxonomy = stack.taxonomy('regions').locale('fr-fr').include_fallback().fetch()
+
+# List all terms in a taxonomy
+terms_result = stack.taxonomy('regions').term().locale('en-us').depth(3).find()
+
+# Fetch a single term
+term = stack.taxonomy('regions').term('california').fetch()
+
+# Term hierarchy traversal
+ancestors = stack.taxonomy('regions').term('san-francisco').depth(5).ancestors()
+descendants = stack.taxonomy('electronics').term('laptops').depth(2).descendants()
+locales = stack.taxonomy('regions').term('california').locales()
+```
+
+`stack.taxonomy()` (no uid) with a filter chained still filters entries by taxonomy, unchanged:
+
+```python
+result = stack.taxonomy().in_('taxonomies.category', ['category1', 'category2']).find()
+```
+
 ### Using the Sync API with Python SDK
 
 The Sync API takes care of syncing your Contentstack data with your application and ensures that the data is always

{contentstack-2.7.0 → contentstack-2.8.0}/Contentstack.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ contentstack/query.py
 contentstack/region_refresh.py
 contentstack/stack.py
 contentstack/taxonomy.py
+contentstack/term.py
 contentstack/utility.py
 contentstack/variants.py
 tests/test_assets.py
@@ -38,4 +39,5 @@ tests/test_live_preview.py
 tests/test_query.py
 tests/test_stack.py
 tests/test_taxonomies.py
+tests/test_taxonomies_unit.py
 tests/test_variants.py

{contentstack-2.7.0 → contentstack-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Contentstack
-Version: 2.7.0
+Version: 2.8.0
 Summary: Contentstack is a headless CMS with an API-first approach.
 Home-page: https://github.com/contentstack/contentstack-python
 Author: Contentstack
@@ -162,6 +162,36 @@ image = stack.image_transform(url, {'width': 100, 'height': 100}).get_url()
 image = stack.image_transform(url, {'auto': 'webp'}).get_url()
 ```
 
+### Working with Taxonomies
+
+Taxonomies published to an environment/locale can be fetched directly via the Content Delivery API.
+
+```python
+# List all published taxonomies
+result = stack.taxonomy().limit(10).include_count().find()
+taxonomies = result['taxonomies']
+
+# Fetch a single taxonomy, with locale fallback
+taxonomy = stack.taxonomy('regions').locale('fr-fr').include_fallback().fetch()
+
+# List all terms in a taxonomy
+terms_result = stack.taxonomy('regions').term().locale('en-us').depth(3).find()
+
+# Fetch a single term
+term = stack.taxonomy('regions').term('california').fetch()
+
+# Term hierarchy traversal
+ancestors = stack.taxonomy('regions').term('san-francisco').depth(5).ancestors()
+descendants = stack.taxonomy('electronics').term('laptops').depth(2).descendants()
+locales = stack.taxonomy('regions').term('california').locales()
+```
+
+`stack.taxonomy()` (no uid) with a filter chained still filters entries by taxonomy, unchanged:
+
+```python
+result = stack.taxonomy().in_('taxonomies.category', ['category1', 'category2']).find()
+```
+
 ### Using the Sync API with Python SDK
 
 The Sync API takes care of syncing your Contentstack data with your application and ensures that the data is always

{contentstack-2.7.0 → contentstack-2.8.0}/README.md

@@ -126,6 +126,36 @@ image = stack.image_transform(url, {'width': 100, 'height': 100}).get_url()
 image = stack.image_transform(url, {'auto': 'webp'}).get_url()
 ```
 
+### Working with Taxonomies
+
+Taxonomies published to an environment/locale can be fetched directly via the Content Delivery API.
+
+```python
+# List all published taxonomies
+result = stack.taxonomy().limit(10).include_count().find()
+taxonomies = result['taxonomies']
+
+# Fetch a single taxonomy, with locale fallback
+taxonomy = stack.taxonomy('regions').locale('fr-fr').include_fallback().fetch()
+
+# List all terms in a taxonomy
+terms_result = stack.taxonomy('regions').term().locale('en-us').depth(3).find()
+
+# Fetch a single term
+term = stack.taxonomy('regions').term('california').fetch()
+
+# Term hierarchy traversal
+ancestors = stack.taxonomy('regions').term('san-francisco').depth(5).ancestors()
+descendants = stack.taxonomy('electronics').term('laptops').depth(2).descendants()
+locales = stack.taxonomy('regions').term('california').locales()
+```
+
+`stack.taxonomy()` (no uid) with a filter chained still filters entries by taxonomy, unchanged:
+
+```python
+result = stack.taxonomy().in_('taxonomies.category', ['category1', 'category2']).find()
+```
+
 ### Using the Sync API with Python SDK
 
 The Sync API takes care of syncing your Contentstack data with your application and ensures that the data is always

{contentstack-2.7.0 → contentstack-2.8.0}/contentstack/__init__.py

@@ -42,7 +42,7 @@ def get_contentstack_endpoint(region='us', service='', omit_https=False):
 __title__ = 'contentstack-delivery-python'
 __author__ = 'contentstack'
 __status__ = 'debug'
-__version__ = 'v2.7.0'
+__version__ = 'v2.8.0'
 __endpoint__ = 'cdn.contentstack.io'
 __email__ = 'support@contentstack.com'
 __developer_email__ = 'mobile@contentstack.com'

{contentstack-2.7.0 → contentstack-2.8.0}/contentstack/stack.py

@@ -8,7 +8,7 @@ from contentstack.asset import Asset
 from contentstack.assetquery import AssetQuery
 from contentstack.contenttype import ContentType
 from contentstack.endpoint import Endpoint
-from contentstack.taxonomy import Taxonomy
+from contentstack.taxonomy import Taxonomy, TaxonomyQuery
 from contentstack.globalfields import GlobalField
 from contentstack.https_connection import HTTPSConnection
 from contentstack.image_transform import ImageTransform
@@ -202,13 +202,35 @@ class Stack:
         """
         return ContentType(self.http_instance, content_type_uid)
     
-    def taxonomy(self):
+    def taxonomy(self, taxonomy_uid: str = None):
         """
-        taxonomy defines the structure or schema of a page or a section
-        of your web or mobile property.
-        :return: taxonomy
+        Without taxonomy_uid: returns a TaxonomyQuery. Chain a filter
+        (in_, or_, and_, exists, above, below, equal_and_above, equal_and_below)
+        then find() to fetch entries filtered by taxonomy (legacy behavior,
+        unchanged). Or call find() directly with nothing chained to list all
+        published taxonomies from the Content Delivery API.
+
+        With taxonomy_uid: returns a Taxonomy for CDA access to that specific
+        published taxonomy (fetch(), term()).
+
+        :param taxonomy_uid: {str} -- (optional) unique identifier of the taxonomy.
+        :return: TaxonomyQuery or Taxonomy
+        -----------------------------
+        Example::
+
+            >>> import contentstack
+            >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
+            >>> # Legacy: filter entries by taxonomy
+            >>> result = stack.taxonomy().in_('taxonomies.color', ['red']).find()
+            >>> # New: list all published taxonomies
+            >>> result = stack.taxonomy().limit(10).find()
+            >>> # New: fetch a single published taxonomy
+            >>> result = stack.taxonomy('regions').fetch()
+        -----------------------------
         """
-        return Taxonomy(self.http_instance)
+        if taxonomy_uid:
+            return Taxonomy(self.http_instance, taxonomy_uid)
+        return TaxonomyQuery(self.http_instance)
     
     def global_field(self, global_field_uid=None):
         """

contentstack-2.8.0/contentstack/taxonomy.py

@@ -0,0 +1,233 @@
+import json
+from urllib.parse import quote
+
+from contentstack.error_messages import ErrorMessages
+from contentstack.utility import Utils
+
+
+class TaxonomyFilter:
+    """
+    Taxonomy entry-filter queries ($above, $below, $in, $exists, ...).
+    Use stack.taxonomy() to instantiate.
+
+    API Reference: https://www.contentstack.com/docs/developers/apis/content-delivery-api/#taxonomies
+    """
+
+    def __init__(self, http_instance):
+        self.http_instance = http_instance
+        self._filters: dict = {}
+
+    def _add(self, field: str, condition: dict) -> "TaxonomyFilter":
+        self._filters[field] = condition
+        return self
+
+    def in_(self, field: str, terms: list) -> "TaxonomyFilter":
+        return self._add(field, {"$in": terms})
+
+    def or_(self, *conds: dict) -> "TaxonomyFilter":
+        return self._add("$or", list(conds))
+
+    def and_(self, *conds: dict) -> "TaxonomyFilter":
+        return self._add("$and", list(conds))
+
+    def exists(self, field: str) -> "TaxonomyFilter":
+        return self._add(field, {"$exists": True})
+
+    def equal_and_below(self, field: str, term_uid: str, levels: int = 10) -> "TaxonomyFilter":
+        cond = {"$eq_below": term_uid, "levels": levels}
+        return self._add(field, cond)
+
+    def below(self, field: str, term_uid: str, levels: int = 10) -> "TaxonomyFilter":
+        cond = {"$below": term_uid, "levels": levels}
+        return self._add(field, cond)
+
+    def equal_and_above(self, field: str, term_uid: str, levels: int = 10) -> "TaxonomyFilter":
+        cond = {"$eq_above": term_uid, "levels": levels}
+        return self._add(field, cond)
+
+    def above(self, field: str, term_uid: str, levels: int = 10) -> "TaxonomyFilter":
+        cond = {"$above": term_uid, "levels": levels}
+        return self._add(field, cond)
+
+    def find(self, params=None):
+        """
+        This method fetches entries filtered by taxonomy from the stack.
+        """
+        self.local_param = {}
+        self.local_param['environment'] = self.http_instance.headers['environment']
+
+        # Ensure query param is always present
+        query_string = json.dumps(self._filters or {})
+        query_encoded = quote(query_string, safe='{}":,[]')  # preserves JSON characters
+
+        # Build the base URL
+        endpoint = self.http_instance.endpoint
+        url = f'{endpoint}/taxonomies/entries?environment={self.local_param["environment"]}&query={query_encoded}'
+
+        # Append any additional params manually
+        if params:
+            other_params = '&'.join(f'{k}={v}' for k, v in params.items())
+            url += f'&{other_params}'
+        return self.http_instance.get(url)
+
+
+class TaxonomyQuery(TaxonomyFilter):
+    """
+    stack.taxonomy() — no uid.
+
+    Chain a filter (in_, or_, and_, exists, above, below, equal_and_above,
+    equal_and_below) then call find() to fetch entries filtered by taxonomy
+    (unchanged legacy behavior, inherited from TaxonomyFilter).
+
+    Call find() directly with nothing chained to list all published
+    taxonomies from the Content Delivery API instead.
+
+    Example::
+
+        >>> import contentstack
+        >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
+        >>> # Legacy: filter entries by taxonomy
+        >>> result = stack.taxonomy().in_('taxonomies.color', ['red']).find()
+        >>> # New: list all published taxonomies
+        >>> result = stack.taxonomy().limit(10).include_count().find()
+    """
+
+    def __init__(self, http_instance):
+        super().__init__(http_instance)
+        self._query_params = {}
+
+    def skip(self, skip: int) -> "TaxonomyQuery":
+        """Sets pagination offset for listing taxonomies.
+        :param skip: {int} -- number of taxonomies to skip
+        :return: TaxonomyQuery, so you can chain this call.
+        """
+        self._query_params['skip'] = skip
+        return self
+
+    def limit(self, limit: int) -> "TaxonomyQuery":
+        """Sets the maximum number of taxonomies to return.
+        :param limit: {int} -- max number of taxonomies to return
+        :return: TaxonomyQuery, so you can chain this call.
+        """
+        self._query_params['limit'] = limit
+        return self
+
+    def include_count(self) -> "TaxonomyQuery":
+        """Includes the total count of taxonomies in the response.
+        :return: TaxonomyQuery, so you can chain this call.
+        """
+        self._query_params['include_count'] = 'true'
+        return self
+
+    def param(self, key: str, value) -> "TaxonomyQuery":
+        """Adds an arbitrary query parameter to the list-taxonomies request
+        (e.g. 'locale').
+        :param key: {str} -- query parameter key
+        :param value: value for the query parameter
+        :return: TaxonomyQuery, so you can chain this call.
+        """
+        if None in (key, value):
+            raise KeyError(ErrorMessages.INVALID_KEY_VALUE_ARGS)
+        self._query_params[key] = value
+        return self
+
+    def find(self, params=None):
+        """
+        If a filter was chained (in_/or_/and_/exists/above/below/...), fetches
+        entries filtered by taxonomy — unchanged legacy behavior.
+        GET /taxonomies/entries?environment=...&query=...
+
+        Otherwise, fetches all published taxonomies from the CDA.
+        GET /taxonomies
+
+        :return: dict -- filtered entries, or {'taxonomies': [...], 'count'?: n}
+        """
+        if self._filters:
+            return super().find(params)
+        if params:
+            self._query_params.update(params)
+        url = f'{self.http_instance.endpoint}/taxonomies'
+        query_str = Utils.do_url_encode(self._query_params)
+        return self.http_instance.get(f'{url}?{query_str}' if query_str else url)
+
+
+class Taxonomy:
+    """
+    Represents a single published taxonomy from the Content Delivery API.
+    Use stack.taxonomy(uid) to instantiate.
+
+    Example::
+
+        >>> import contentstack
+        >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
+        >>> taxonomy = stack.taxonomy('regions').locale('fr-fr').include_fallback()
+        >>> result = taxonomy.fetch()
+    """
+
+    def __init__(self, http_instance, taxonomy_uid: str):
+        if not taxonomy_uid:
+            raise KeyError(ErrorMessages.INVALID_KEY_OR_VALUE)
+        self.http_instance = http_instance
+        self._taxonomy_uid = taxonomy_uid
+        self._url = f'{http_instance.endpoint}/taxonomies/{taxonomy_uid}'
+        self._query_params = {}
+
+    def term(self, term_uid: str = None):
+        """
+        Without term_uid: returns TermQuery for listing all terms in this taxonomy.
+        With term_uid: returns Term for a specific term.
+
+        :param term_uid: {str} -- (optional) unique identifier of the term.
+        :return: Term or TermQuery
+        """
+        from contentstack.term import Term, TermQuery
+        if term_uid:
+            return Term(self.http_instance, self._taxonomy_uid, term_uid)
+        return TermQuery(self.http_instance, self._taxonomy_uid)
+
+    def locale(self, locale: str) -> "Taxonomy":
+        """Sets the locale for this taxonomy fetch (e.g. 'en-us', 'fr-fr').
+        :param locale: {str} -- locale code
+        :return: Taxonomy, so you can chain this call.
+        """
+        self._query_params['locale'] = locale
+        return self
+
+    def include_fallback(self) -> "Taxonomy":
+        """Enables locale fallback through the branch hierarchy.
+        If the taxonomy is not published in the requested locale, falls back
+        to the parent locale in the branch hierarchy.
+        :return: Taxonomy, so you can chain this call.
+        """
+        self._query_params['include_fallback'] = 'true'
+        return self
+
+    def include_branch(self) -> "Taxonomy":
+        """Includes the _branch field in the response.
+        :return: Taxonomy, so you can chain this call.
+        """
+        self._query_params['include_branch'] = 'true'
+        return self
+
+    def param(self, key: str, value) -> "Taxonomy":
+        """Adds an arbitrary query parameter.
+        :param key: {str} -- query parameter key
+        :param value: value for the query parameter
+        :return: Taxonomy, so you can chain this call.
+        """
+        if None in (key, value):
+            raise KeyError(ErrorMessages.INVALID_KEY_VALUE_ARGS)
+        self._query_params[key] = value
+        return self
+
+    def fetch(self) -> dict:
+        """
+        Fetches this taxonomy from the CDA.
+        GET /taxonomies/{taxonomy_uid}
+
+        :return: dict -- the taxonomy object.
+        """
+        query_str = Utils.do_url_encode(self._query_params)
+        url = f'{self._url}?{query_str}' if query_str else self._url
+        response = self.http_instance.get(url)
+        return response.get('taxonomy', response)

contentstack-2.8.0/contentstack/term.py

@@ -0,0 +1,194 @@
+from contentstack.error_messages import ErrorMessages
+from contentstack.utility import Utils
+
+
+class Term:
+    """
+    Represents a single published taxonomy term.
+    Supports hierarchy traversal: ancestors(), descendants(), locales().
+    Use stack.taxonomy(uid).term(term_uid) to instantiate.
+
+    Example::
+
+        >>> import contentstack
+        >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
+        >>> term = stack.taxonomy('regions').term('california')
+        >>> result = term.fetch()
+    """
+
+    def __init__(self, http_instance, taxonomy_uid: str, term_uid: str):
+        if not term_uid:
+            raise KeyError(ErrorMessages.INVALID_KEY_OR_VALUE)
+        self.http_instance = http_instance
+        self._url = f'{http_instance.endpoint}/taxonomies/{taxonomy_uid}/terms/{term_uid}'
+        self._query_params = {}
+
+    def depth(self, depth: int) -> "Term":
+        """Limits the depth of hierarchy traversal for ancestors()/descendants().
+        :param depth: {int} -- maximum hierarchy depth
+        :return: Term, so you can chain this call.
+        """
+        self._query_params['depth'] = depth
+        return self
+
+    def locale(self, locale: str) -> "Term":
+        """Sets the locale for this term fetch (e.g. 'en-us', 'fr-fr').
+        :param locale: {str} -- locale code
+        :return: Term, so you can chain this call.
+        """
+        self._query_params['locale'] = locale
+        return self
+
+    def include_fallback(self) -> "Term":
+        """Enables locale fallback through the branch hierarchy.
+        :return: Term, so you can chain this call.
+        """
+        self._query_params['include_fallback'] = 'true'
+        return self
+
+    def include_branch(self) -> "Term":
+        """Includes the _branch field in the response.
+        :return: Term, so you can chain this call.
+        """
+        self._query_params['include_branch'] = 'true'
+        return self
+
+    def param(self, key: str, value) -> "Term":
+        """Adds an arbitrary query parameter.
+        :param key: {str} -- query parameter key
+        :param value: value for the query parameter
+        :return: Term, so you can chain this call.
+        """
+        if None in (key, value):
+            raise KeyError(ErrorMessages.INVALID_KEY_VALUE_ARGS)
+        self._query_params[key] = value
+        return self
+
+    def _get(self, suffix: str = '', key: str = None):
+        url = f'{self._url}{suffix}'
+        query_str = Utils.do_url_encode(self._query_params)
+        response = self.http_instance.get(f'{url}?{query_str}' if query_str else url)
+        return response.get(key, response) if key else response
+
+    def fetch(self) -> dict:
+        """
+        Fetches this term.
+        GET /taxonomies/{taxonomy_uid}/terms/{term_uid}
+        :return: dict -- the term object.
+        """
+        return self._get(key='term')
+
+    def locales(self) -> dict:
+        """
+        Fetches all published localized versions of this term.
+        GET /taxonomies/{taxonomy_uid}/terms/{term_uid}/locales
+        :return: dict -- the localized terms.
+        """
+        return self._get('/locales', key='terms')
+
+    def ancestors(self) -> list:
+        """
+        Fetches all ancestor terms up to the root.
+        GET /taxonomies/{taxonomy_uid}/terms/{term_uid}/ancestors
+        :return: list -- the ancestor terms.
+        """
+        return self._get('/ancestors', key='terms')
+
+    def descendants(self) -> list:
+        """
+        Fetches all descendant terms.
+        GET /taxonomies/{taxonomy_uid}/terms/{term_uid}/descendants
+        :return: list -- the descendant terms.
+        """
+        return self._get('/descendants', key='terms')
+
+
+class TermQuery:
+    """
+    Query builder for fetching all terms in a taxonomy.
+    Use stack.taxonomy(uid).term() to instantiate.
+
+    Example::
+
+        >>> import contentstack
+        >>> stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
+        >>> result = stack.taxonomy('regions').term().locale('en-us').depth(3).find()
+    """
+
+    def __init__(self, http_instance, taxonomy_uid: str):
+        self.http_instance = http_instance
+        self._url = f'{http_instance.endpoint}/taxonomies/{taxonomy_uid}/terms'
+        self._query_params = {}
+
+    def depth(self, depth: int) -> "TermQuery":
+        """Limits term hierarchy traversal depth.
+        :param depth: {int} -- maximum hierarchy depth
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['depth'] = depth
+        return self
+
+    def skip(self, skip: int) -> "TermQuery":
+        """Sets pagination offset.
+        :param skip: {int} -- number of terms to skip
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['skip'] = skip
+        return self
+
+    def limit(self, limit: int) -> "TermQuery":
+        """Sets the maximum number of terms to return.
+        :param limit: {int} -- max number of terms to return
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['limit'] = limit
+        return self
+
+    def locale(self, locale: str) -> "TermQuery":
+        """Filters terms by locale (e.g. 'en-us', 'fr-fr').
+        :param locale: {str} -- locale code
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['locale'] = locale
+        return self
+
+    def include_fallback(self) -> "TermQuery":
+        """Enables locale fallback through the branch hierarchy.
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['include_fallback'] = 'true'
+        return self
+
+    def include_branch(self) -> "TermQuery":
+        """Includes the _branch field in the response.
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['include_branch'] = 'true'
+        return self
+
+    def include_count(self) -> "TermQuery":
+        """Includes the total count of terms in the response.
+        :return: TermQuery, so you can chain this call.
+        """
+        self._query_params['include_count'] = 'true'
+        return self
+
+    def param(self, key: str, value) -> "TermQuery":
+        """Adds an arbitrary query parameter.
+        :param key: {str} -- query parameter key
+        :param value: value for the query parameter
+        :return: TermQuery, so you can chain this call.
+        """
+        if None in (key, value):
+            raise KeyError(ErrorMessages.INVALID_KEY_VALUE_ARGS)
+        self._query_params[key] = value
+        return self
+
+    def find(self) -> dict:
+        """
+        Fetches all terms in the taxonomy.
+        GET /taxonomies/{taxonomy_uid}/terms
+        :return: dict -- {'terms': [...], 'count'?: n}
+        """
+        query_str = Utils.do_url_encode(self._query_params)
+        return self.http_instance.get(f'{self._url}?{query_str}' if query_str else self._url)