contentful package

Submodules

contentful.array module

contentful.array

This module implements the Array class.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/collection-resources-and-pagination

copyright:

  1. 2017 by Contentful GmbH.

license:

MIT, see LICENSE for more details.

class contentful.array.Array(json, items)[source]

Bases: object

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/collection-resources-and-pagination

contentful.asset module

class contentful.asset.Asset(item, includes=None, errors=None, localized=False, resources=None, **kwargs)[source]

Bases: FieldsResource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/assets

incoming_references(client=None, query=None)[source]

Fetches all entries referencing the asset

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/links-to-asset :param client Client instance :param query: (optional) Dict with API options. :return: List of Entry objects. :rtype: List of contentful.entry.Entry

Usage:
>>> entries = asset.incoming_references(client)
[<Entry[cat] id='happycat'>]
url(**kwargs)[source]

Returns a formatted URL for the Asset’s File with serialized parameters.

Usage:
>>> my_asset.url()
"//images.contentful.com/spaces/foobar/..."
>>> my_asset.url(w=120, h=160)
"//images.contentful.com/spaces/foobar/...?w=120&h=160"

contentful.asset_key module

class contentful.asset_key.AssetKey(item, **kwargs)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/asset-keys

contentful.client module

class contentful.client.Client(space_id, access_token, api_url='cdn.contentful.com', api_version=1, default_locale='en-US', environment='master', https=True, authorization_as_header=True, raw_mode=False, gzip_encoded=True, raise_errors=True, content_type_cache=True, reuse_entries=False, timeout_s=1, proxy_host=None, proxy_port=None, proxy_username=None, proxy_password=None, max_rate_limit_retries=1, max_rate_limit_wait=60, max_include_resolution_depth=20, application_name=None, application_version=None, integration_name=None, integration_version=None, additional_tokens=None)[source]

Bases: object

Constructs the API Client.

Parameters:

  • space_id – Space ID of your target space.

  • access_token – API Access Token (Delivery by default, Preview if overriding api_url).

  • api_url – (optional) URL of the Contentful Target API, defaults to Delivery API (can be overriden for Preview API).

  • api_version – (optional) Target version of the Contentful API.

  • default_locale – (optional) Default Locale for your Space, defaults to ‘en-US’.

  • environment – (optional) Default Environment for client, defaults to ‘master’.

  • https – (optional) Boolean determining wether to use https or http, defaults to True.

  • authorization_as_header – (optional) Boolean determining wether to send access_token through a header or via GET params, defaults to True.

  • raw_mode – (optional) Boolean determining wether to process the response or return it raw after each API call, defaults to False.

  • gzip_encoded – (optional) Boolean determining wether to accept gzip encoded results, defaults to True.

  • raise_errors – (optional) Boolean determining wether to raise an exception on requests that aren’t successful, defaults to True.

  • content_type_cache – (optional) Boolean determining wether to store a Cache of the Content Types in order to properly coerce Entry fields, defaults to True.

  • reuse_entries – (optional) Boolean determining wether to reuse hydrated Entry and Asset objects within the same request when possible. Defaults to False

  • timeout_s – (optional) Max time allowed for each API call, in seconds. Defaults to 1s.

  • proxy_host – (optional) URL for Proxy, defaults to None.

  • proxy_port – (optional) Port for Proxy, defaults to None.

  • proxy_username – (optional) Username for Proxy, defaults to None.

  • proxy_password – (optional) Password for Proxy, defaults to None.

  • max_rate_limit_retries – (optional) Maximum amount of retries after RateLimitError, defaults to 1.

  • max_rate_limit_wait – (optional) Timeout (in seconds) for waiting for retry after RateLimitError, defaults to 60.

  • max_include_resolution_depth – (optional) Maximum include resolution level for Resources, defaults to 20 (max include level * 2).

  • application_name – (optional) User application name, defaults to None.

  • application_version – (optional) User application version, defaults to None.

  • integration_name – (optional) Integration name, defaults to None.

  • integration_version – (optional) Integration version, defaults to None.

  • additional_tokens – (optional) Additional tokens to be sent in the headers for resource resolution, defaults to None.

Returns:

Client object.

Return type:

contentful.Client

Usage:

>>> import contentful
>>> client = contentful.Client('cfexampleapi', 'b4c0n73n7fu1')
<contentful.Client space_id="cfexampleapi"
  access_token="b4c0n73n7fu1"
  default_locale="en-US">
asset(asset_id, query=None)[source]

Fetches an Asset by ID.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/assets/asset/get-a-single-asset

Parameters:

  • asset_id – The ID of the target Asset.

  • query – (optional) Dict with API options.

Returns:

Asset object.

Return type:

contentful.asset.Asset

Usage:
>>> nyancat_asset = client.asset('nyancat')
<Asset id='nyancat' url='//images.contentful.com/cfex...'>
assets(query=None)[source]

Fetches all Assets from the Space (up to the set limit, can be modified in query).

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/assets/assets-collection/get-all-assets-of-a-space

Parameters:

query – (optional) Dict with API options.

Returns:

List of Asset objects.

Return type:

List of contentful.asset.Asset

Usage:
>>> assets = client.assets()
[<Asset id='1x0xpXu4pSGS4OukSyWGUK' url='//images.content...'>,
 <Asset id='happycat' url='//images.contentful.com/cfexam...'>,
 <Asset id='nyancat' url='//images.contentful.com/cfexamp...'>,
 <Asset id='jake' url='//images.contentful.com/cfexamplea...'>]
content_type(content_type_id, query=None)[source]

Fetches a Content Type by ID.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/content-types/content-type/get-a-single-content-type

Parameters:

  • content_type_id – The ID of the target Content Type.

  • query – (optional) Dict with API options.

Returns:

ContentType object.

Return type:

contentful.content_type.ContentType

Usage:
>>> cat_content_type = client.content_type('cat')
<ContentType[Cat] id='cat'>
content_types(query=None)[source]

Fetches all Content Types from the Space.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/content-types/content-model/get-the-content-model-of-a-space

Parameters:

query – (optional) Dict with API options.

Returns:

List of ContentType objects.

Return type:

List of contentful.content_type.ContentType

Usage:
>>> content_types = client.content_types()
[<ContentType[City] id='1t9IbcfdCk6m04uISSsaIK'>,
 <ContentType[Human] id='human'>,
 <ContentType[Dog] id='dog'>,
 <ContentType[Cat] id='cat'>]
create_asset_key(expires_at)[source]

Creates an asset key for signing embargoed asset URLs. API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/asset-keys/create-asset-key :param expires_at: (optional) Unix timestamp when the key should expire (max 48h from now). :return: Dict containing policy and secret for signing URLs. :rtype: dict

Usage:
>>> asset_key = client.create_asset_key()
{'policy': 'policy_string', 'secret': 'secret_string'}
entries(query=None)[source]

Fetches all Entries from the Space (up to the set limit, can be modified in query).

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/entries/entries-collection/get-all-entries-of-a-space

Parameters:

query – (optional) Dict with API options.

Returns:

List of Entry objects.

Return type:

List of contentful.entry.Entry

Usage:
>>> entries = client.entries()
[<Entry[cat] id='happycat'>,
 <Entry[1t9IbcfdCk6m04uISSsaIK] id='5ETMRzkl9KM4omyMwKAOki'>,
 <Entry[dog] id='6KntaYXaHSyIw8M6eo26OK'>,
 <Entry[1t9IbcfdCk6m04uISSsaIK] id='7qVBlCjpWE86Oseo40gAEY'>,
 <Entry[cat] id='garfield'>,
 <Entry[1t9IbcfdCk6m04uISSsaIK] id='4MU1s3potiUEM2G4okYOqw'>,
 <Entry[cat] id='nyancat'>,
 <Entry[1t9IbcfdCk6m04uISSsaIK] id='ge1xHyH3QOWucKWCCAgIG'>,
 <Entry[human] id='finn'>,
 <Entry[dog] id='jake'>]
entry(entry_id, query=None)[source]

Fetches an Entry by ID.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/entries/entry/get-a-single-entry

Parameters:

  • entry_id – The ID of the target Entry.

  • query – (optional) Dict with API options.

Returns:

Entry object.

Return type:

contentful.entry.Entry

Usage:
>>> nyancat_entry = client.entry('nyancat')
<Entry[cat] id='nyancat'>
environment_url(url)[source]

Formats the URL with the environment.

locales(query=None)[source]

Fetches all Locales from the Environment (up to the set limit, can be modified in query).

# TODO: fix url API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/assets/assets-collection/get-all-assets-of-a-space

Parameters:

query – (optional) Dict with API options.

Returns:

List of Locale objects.

Return type:

List of contentful.locale.Locale

Usage:
>>> locales = client.locales()
[<Locale[English (United States)] code='en-US' default=True fallback_code=None optional=False>]
space(query=None)[source]

Fetches the current Space.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/spaces/get-a-space

Parameters:

query – (optional) Dict with API options.

Returns:

Space object.

Return type:

contentful.space.Space

Usage:

>>> space = client.space()
<Space[Contentful Example API] id='cfexampleapi'>
sync(query=None)[source]

Fetches content from the Sync API.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization/initial-synchronization/query-entries

Parameters:

query – (optional) Dict with API options.

Returns:

SyncPage object.

Return type:

contentful.sync_page.SyncPage

Usage:
>>> sync_page = client.sync({'initial': True})
<SyncPage next_sync_token='w5ZGw6JFwqZmVcKsE8Kow4grw45QdybC...'>
taxonomy_concept(concept_id, query=None)[source]

Fetches a single taxonomy concept by ID. :param concept_id: The ID of the target concept. :param query: (optional) Dict with API options. :return: TaxonomyConcept object. :rtype: contentful.taxonomy_concept.TaxonomyConcept

Usage:
>>> concept = client.taxonomy_concept('3DMf5gdax6J22AfcJ6fvsC')
<TaxonomyConcept id='3DMf5gdax6J22AfcJ6fvsC'>
taxonomy_concept_scheme(scheme_id, query=None)[source]

Fetches a single taxonomy concept scheme by ID. :param scheme_id: The ID of the target concept scheme. :param query: (optional) Dict with API options. :return: TaxonomyConceptScheme object. :rtype: contentful.taxonomy_concept_scheme.TaxonomyConceptScheme

Usage:
>>> scheme = client.taxonomy_concept_scheme('7CzXPy6XvYYd0D7SomitgI')
<TaxonomyConceptScheme id='7CzXPy6XvYYd0D7SomitgI'>
taxonomy_concept_schemes(query=None)[source]

Fetches all taxonomy concept schemes. :param query: (optional) Dict with API options. :return: Array of TaxonomyConceptScheme objects. :rtype: contentful.array.Array

Usage:
>>> schemes = client.taxonomy_concept_schemes()
<Array size=1 total=1 limit=100 skip=0>
taxonomy_concepts(query=None)[source]

Fetches all taxonomy concepts. :param query: (optional) Dict with API options. :return: Array of TaxonomyConcept objects. :rtype: contentful.array.Array

Usage:
>>> concepts = client.taxonomy_concepts()
<Array size=1 total=1 limit=100 skip=0>

contentful.content_type module

class contentful.content_type.ContentType(item, **kwargs)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/content-types

field_for(field_id)[source]

Fetches the field for the given Field ID.

Parameters:

field_id – ID for Field to fetch.

Returns:

ContentTypeField object.

Return type:

contentful.ContentTypeField

contentful.content_type_cache module

contentful.content_type_cache

This module implements the ContentTypeCache class.

copyright:

  1. 2016 by Contentful GmbH.

license:

MIT, see LICENSE for more details.

class contentful.content_type_cache.ContentTypeCache[source]

Bases: object

Cache for Content Types.

Used for properly coercing Entry fields.

classmethod get(space_id, content_type_id)[source]

Fetches a Content Type from the Cache.

classmethod update_cache(client)[source]

Updates the Cache with all Content Types from the Space.

contentful.content_type_field module

class contentful.content_type_field.ContentTypeField(field_data)[source]

Bases: object

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/content-types

coerce(value, **kwargs)[source]

Coerces the value to the proper type.

contentful.content_type_field_types module

class contentful.content_type_field_types.ArrayField(items=None)[source]

Bases: BasicField

Array Coercion Class

Coerces items in collection with it’s proper Coercion Class.

coerce(value, **kwargs)[source]

Coerces array items with proper coercion.

class contentful.content_type_field_types.BasicField(items=None)[source]

Bases: object

Base Coercion Class

coerce(value, **kwargs)[source]

Just returns the value.

class contentful.content_type_field_types.BooleanField(items=None)[source]

Bases: BasicField

Boolean Coercion Class

coerce(value, **kwargs)[source]

Coerces value to boolean

class contentful.content_type_field_types.DateField(items=None)[source]

Bases: BasicField

Date Coercion Class

coerce(value, **kwargs)[source]

Coerces ISO8601 date to datetime.datetime object.

class contentful.content_type_field_types.IntegerField(items=None)[source]

Bases: BasicField

Integer Coercion Class

coerce(value, **kwargs)[source]

Coerces value to int

class contentful.content_type_field_types.LinkField(items=None)[source]

Bases: BasicField

Nothing should be done here as include resolution is handled within entries due to depth handling (explained within Entry). Only present as a placeholder for proper resolution within ContentType.

class contentful.content_type_field_types.LocationField(items=None)[source]

Bases: BasicField

Location Coercion Class

coerce(value, **kwargs)[source]

Coerces value to Location object

class contentful.content_type_field_types.NumberField(items=None)[source]

Bases: BasicField

Number Coercion Class

coerce(value, **kwargs)[source]

Coerces value to float

class contentful.content_type_field_types.ObjectField(items=None)[source]

Bases: BasicField

Object Coercion Class.

coerce(value, **kwargs)[source]

Coerces JSON values properly.

class contentful.content_type_field_types.ResourceLinkField(items=None)[source]

Bases: BasicField

Nothing should be done here as include resolution is handled within entries. Only present as a placeholder for proper resolution within ContentType.

class contentful.content_type_field_types.RichTextField(items=None)[source]

Bases: BasicField

Coerces Rich Text fields and resolves includes for entries included.

coerce(value, includes=None, errors=None, resources=None, default_locale='en-US', locale=None)[source]

Coerces Rich Text properly.

class contentful.content_type_field_types.SymbolField(items=None)[source]

Bases: BasicField

Symbol Coercion Class

coerce(value, **kwargs)[source]

Coerces value to str

class contentful.content_type_field_types.TextField(items=None)[source]

Bases: BasicField

Text Coercion Class

coerce(value, **kwargs)[source]

Coerces value to str

contentful.deleted_asset module

class contentful.deleted_asset.DeletedAsset(item, default_locale='en-US', includes=None, errors=None, localized=False, resources=None, depth=0, max_depth=20)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization

contentful.deleted_entry module

class contentful.deleted_entry.DeletedEntry(item, default_locale='en-US', includes=None, errors=None, localized=False, resources=None, depth=0, max_depth=20)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization

contentful.entry module

class contentful.entry.Entry(item, includes=None, errors=None, localized=False, resources=None, **kwargs)[source]

Bases: FieldsResource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/entries

incoming_references(client=None, query=None)[source]

Fetches all entries referencing the entry

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/links-to-asset

:param client Client instance :param query: (optional) Dict with API options. :return: List of Entry objects. :rtype: List of contentful.entry.Entry

Usage:
>>> entries = entry.incoming_references(client)
[<Entry[cat] id='happycat'>]

contentful.errors module

contentful.errors

This module implements the Error classes.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/errors

copyright:

  1. 2016 by Contentful GmbH.

license:

MIT, see LICENSE for more details.

exception contentful.errors.AccessDeniedError(response)[source]

Bases: HTTPError

403

exception contentful.errors.BadGatewayError(response)[source]

Bases: HTTPError

502

exception contentful.errors.BadRequestError(response)[source]

Bases: HTTPError

400

exception contentful.errors.EntryNotFoundError[source]

Bases: Exception

Error for entry not found.

exception contentful.errors.HTTPError(response)[source]

Bases: Exception

Base HTTP Error Class

exception contentful.errors.NotFoundError(response)[source]

Bases: HTTPError

404

exception contentful.errors.RateLimitExceededError(response)[source]

Bases: HTTPError

429

RATE_LIMIT_RESET_HEADER_KEY = 'x-contentful-ratelimit-reset'
reset_time()[source]

Returns the reset time in seconds until next available request.

exception contentful.errors.ServerError(response)[source]

Bases: HTTPError

500

exception contentful.errors.ServiceUnavailableError(response)[source]

Bases: HTTPError

503

exception contentful.errors.UnauthorizedError(response)[source]

Bases: HTTPError

401

contentful.errors.get_error(response)[source]

Gets Error by HTTP Status Code

contentful.locale module

class contentful.locale.Locale(item, **kwargs)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/localization

contentful.resource module

class contentful.resource.FieldsResource(item, includes=None, errors=None, localized=False, resources=None, **kwargs)[source]

Bases: Resource

Fields Resource Class

Implements locale handling for Resource fields.

fields(locale=None)[source]

Get fields for a specific locale

Parameters:

locale – (optional) Locale to fetch, defaults to default_locale.

property locale

Bases: Resource

Link Class

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/links

resolve(client)[source]

Resolves Link to a specific Resource

class contentful.resource.Resource(item, default_locale='en-US', includes=None, errors=None, localized=False, resources=None, depth=0, max_depth=20)[source]

Bases: object

Base Resource Class

Implements common resource attributes.

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/common-resource-attributes

Bases: Resource

Resource Link Class

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/resource-links

contentful.resource_builder module

class contentful.resource_builder.ResourceBuilder(default_locale, localized, json, includes_for_single=None, errors_for_single=None, reuse_entries=False, resources=None, depth=0, max_depth=20)[source]

Bases: object

Creates objects of the proper Resource Type

build()[source]

Creates the objects from the JSON response

contentful.space module

class contentful.space.Space(item, **kwargs)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/spaces

contentful.sync_page module

class contentful.sync_page.SyncPage(item, **kwargs)[source]

Bases: Resource

API Reference: https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization

next(client)[source]

Fetches next SyncPage

Parameters:

client – CDA Client.

Returns:

SyncPage

Return type:

contentful.sync_page.SyncPage

contentful.taxonomy_concept module

class contentful.taxonomy_concept.TaxonomyConcept(item, **kwargs)[source]

Bases: Resource

Represents a single taxonomy concept.

contentful.taxonomy_concept_scheme module

class contentful.taxonomy_concept_scheme.TaxonomyConceptScheme(item, **kwargs)[source]

Bases: Resource

Represents a single taxonomy concept scheme.

contentful.utils module

exception contentful.utils.ConfigurationException[source]

Bases: Exception

Configuration Error Class

exception contentful.utils.NotSupportedException[source]

Bases: Exception

This exception is thrown when something is not supported by the API.

Checks if value is link or not.

Parameters:

value – any object.

Returns:

Boolean

Return type:

bool

Usage:
>>> is_link('foo')
False
>>> is_link({'sys': {'type': 'Link', 'id': 'foobar'}})
True

Checks if value is an array of links.

Parameters:

value – any object.

Returns:

Boolean

Return type:

bool

Usage:
>>> is_link_array('foo')
False
>>> is_link_array([1, 2, 3])
False
>>> is_link([{'sys': {'type': 'Link', 'id': 'foobar'}}])
True

Checks if value is a resource link or not.

Parameters:

value – any object.

Returns:

Boolean

Return type:

bool

Usage:
>>> is_resource_link('foo')
False
>>> is_resource_link({'sys': {'type': 'ResourceLink', 'urn': 'foobar'}})
True
contentful.utils.json_error_class()[source]

Returns the class for JSON decode errors depends on the Python version.

Returns the resource that matches the link

class contentful.utils.retry_request(client)[source]

Bases: object

Decorator to retry function calls in case they raise rate limit exceptions

contentful.utils.snake_case(a_string)[source]

Returns a snake cased version of a string.

Parameters:

a_string – any str object.

Usage:
>>> snake_case('FooBar')
"foo_bar"
contentful.utils.string_class()[source]

Returns the parent class for strings depends on the Python version.

contentful.utils.unicode_class()[source]

Returns the class that allows for unicode encoded strings depends on the Python version.

contentful.utils.unresolvable(item, errors)[source]

Module contents