Contentful Management API Client
Project description
Contentful provides a content infrastructure for digital teams to power content in websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship digital products faster.
Installation
Install Contentful Management from the Python Package Index:
sudo pip install contentful_management
Usage
Client
Create a client:
import contentful_management client = contentful_management.Client('MANAGEMENT_API_TOKEN')
The api token can easily be created through the management api documentation.
Spaces
Retrieving all spaces:
spaces = client.spaces().all()
Retrieveing one space by ID:
blog_space = client.spaces().find('blog_space_id')
Deleting a space:
client.spaces().delete('blog_space_id') # or if you already fetched the space blog_space.delete()
Creating a new space:
new_blog_space = client.spaces().create({'name': 'My Blog', 'default_locale': 'en-US'}) # default_locale is optional
In the case your user belongs to multiple organizations, you’re required to send an organization ID:
new_blog_space = client.spaces().create({'name': 'My Blog', 'organization_id': 'my_org_id'})
Updating a space:
blog_space.update({'name': 'Ye Olde Blog'}) # or directly editing it's properties blog_space.name = 'Ye Olde Blog' blog_space.save()
Space Memberships
Retrieving all memberships on a space:
memberships = client.memberships('my_space_id').all() # or if you already have a fetched space memberships = space.memberships().all()
Retrieveing one membership by ID:
membership = client.memberships('my_space_id').find('membership_id') # or if you already have a fetched space membership = space.memberships().find('membership_id')
Deleting an membership:
client.memberships('my_space_id').delete('membership_id') # or if you already have a fetched space space.memberships().delete('membership_id') # or if you already have fetched the membership memberships.delete()
Creating a new membership:
memberships = client.memberships('my_space_id').create({ "admin": False, "roles": [ { "type": "Link", "linkType": "Role", "id": "1Nq88dKTNXNaxkbrRpEEw6" } ], "email": "test@example.com" }) # or if you already have a fetched space memberships = space.memberships().create({ "admin": False, "roles": [ { "type": "Link", "linkType": "Role", "id": "1Nq88dKTNXNaxkbrRpEEw6" } ], "email": "test@example.com" })
Updating a membership:
memberships.update({ "admin": False, "roles": [ { "type": "Link", "linkType": "Role", "id": "1Nq88dKTNXNaxkbrRpEEw6" } ] }) # or directly editing it's properties memberships.admin = True memberships.save()
Organizations
Retrieving all Organizations you belong to:
organizations = client.organizations().all()
Usage API
Note: This feature is available only to Commited v2 customers.
Organization Periodic Usages
Retrieving all API Usage statistics for an Organization during a given usage period, broken down by organization for all APIs:
# Optionally, you can pass the metric, start and end date filters usage = client.organization_periodic_usages('organization_id').all() # For example only CDA and CMA metrics from yesterday onwards usage = client.organization_periodic_usages('organization_id').all({'metric[in]': ['cda', 'cma'], 'startDate': (date.today() - timedelta(days=1)).isoformat()})
Alternatively, if you have an already fetched organization:
usage_periods = organization.periodic_usages().all()
Users
Retrieving your User information:
user = client.users().me()
Retrieving one user by ID from the space:
user = space.users().find(user_id)
Retrieving one user by ID from an organization:
user = organization.users().find(user_id)
Environments
Note: For all resources that depend on an environment but don’t have environments explicitly enabled. You should use 'master' as environment_id.
Retrieving all environments on a space:
environments = client.environments('my_space_id').all() # or if you already have a fetched space environments = space.environments().all()
Retrieving an environment by ID:
environment = client.environments('my_space_id').find('environment_id') # or if you already have a fetched space environment = space.environments().find('environment_id')
Deleting an environment:
client.environments('my_space_id').delete('environment_id') # or if you already have a fetched space space.environments().delete('environment_id') # or if you already fetched the environment environment.delete()
Creating an environment:
new_environment = client.environments('my_space_id').create( 'new_environment_id', { 'name': 'New Environment' } ) # or if you already have a fetched space new_environment = space.environments().create( 'new_environment_id', { 'name': 'New Environment' } )
Creating an environment with a different source:
new_environment = client.environments('my_space_id').create( 'new_environment_id', { 'name': 'New Environment', 'source_environment_id': 'other_environment' } )
Assets
Retrieving all assets on a space:
assets = client.assets('my_space_id', 'environment_id').all() # or if you already have a fetched environment assets = environment.assets().all()
Retrieving an asset by ID:
asset = client.assets('my_space_id', 'environment_id').find('asset_id') # or if you already have a fetched environment asset = environment.assets().find('asset_id')
Deleting an asset:
client.assets('my_space_id', 'environment_id').delete('asset_id') # or if you already have a fetched environment environment.assets().delete('asset_id') # or if you already fetched the asset asset.delete()
Creating an asset:
file_attributes = { 'fields': { 'file': { 'en-US': { 'fileName': 'file.png', 'contentType': 'image/png', 'upload': 'https://url.to/file.png' } } } } new_asset = client.assets('my_space_id', 'environment_id').create( 'new_asset_id', file_attributes ) # or if you already have a fetched environment new_asset = environment.assets().create( 'new_asset_id', file_attributes )
We also support Direct File Upload, this will be explained in the Uploads section.
Processing an asset:
asset.process()
This will process the file for every available locale and provide you with a downloadable URL within Contentful.
Updating an asset:
asset.update(other_file_attributes) # or directly editing it's properties asset.file['file_name'] = 'other_file.png' asset.save()
Deleting an asset:
client.assets('my_space_id', 'environment_id').delete('asset_id') # or if you already have a fetched environment environment.assets().delete('asset_id') # or if you already fetched the asset asset.delete()
Archiving and Unarchiving an asset:
asset.archive() asset.unarchive()
Publishing or Unpublishing an asset:
asset.publish() asset.unpublish()
Checking if an asset is published:
asset.is_published
Checking if an asset is updated:
asset.is_updated
Entries
Retrieving all entries on a space:
entries = client.entries('my_space_id', 'environment_id').all() # or if you already have a fetched environment entries = environment.entries().all() # or if you already have a fetched content type entries_for_content_type = content_type.entries().all()
Retrieving an entry by ID:
entry = client.entries('my_space_id', 'environment_id').find('entry_id') # or if you already have a fetched environment entry = environment.entries().find('entry_id') # or if you already have a fetched content type entry = content_type.entries().find('entry_id')
Deleting an entry:
client.entries('my_space_id', 'environment_id').delete('entry_id') # or if you already have a fetched environment environment.entries().delete('entry_id') # or if you already fetched the entry entry.delete()
Creating an entry:
entry_attributes = { 'content_type_id': 'target_content_type', 'fields': { 'title': { 'en-US': 'My Awesome Post' }, 'body': { 'en-US': 'Once upon a time...' } } } new_entry = client.entries('my_space_id', 'environment_id').create( 'new_entry_id', entry_attributes ) # or if you already have a fetched environment new_entry = environment.entries().create( 'new_entry_id', entry_attributes )
Updating an entry:
entry.update(other_entry_attributes) # or directly updating it's properties entry.title = 'My Super Post' entry.save()
Updating an entry for multiple locales:
for target_locale in ['en-US', 'es-AR']: entry.sys['locale'] = target_locale entry.title = 'Post in {0}'.format(target_locale) entry.save() entry.fields('en-US')['title'] # will return "Post in en-US" entry.fields('es-AR')['title'] # will return "Post in es-AR"
Accessing localized fields:
entry.sys['locale'] = 'es-AR' entry.title # will now be equivalent to entry.fields('es-AR')['title']
Deleting an entry:
client.entries('my_space_id', 'environment_id').delete('entry_id') # or if you already have a fetched environment environment.entries().delete('entry_id') # or if you already fetched the entry entry.delete()
Archiving and Unarchiving an entry:
entry.archive() entry.unarchive()
Publishing or Unpublishing an entry:
entry.publish() entry.unpublish()
Checking if an entry is published:
entry.is_published
Checking if an entry is updated:
entry.is_updated
Note:
Entries created with empty fields, will not return those fields in the response. Therefore, if you want to explicitly set those fields to empty (None) you will need to make an extra request to fetch the Content Type and fill the missing fields.
Content Types
Retrieving all content types on a space:
content_types = client.content_types('my_space_id', 'environment_id').all() # or if you already have a fetched environment content_types = environment.content_types().all()
Retrieving a content type by ID:
content_type = client.content_types('my_space_id', 'environment_id').find('content_type_id') # or if you already have a fetched environment content_type = environment.content_types().find('content_type_id')
Deleting a content type:
client.content_types('my_space_id', 'environment_id').delete('content_type_id') # or if you already have a fetched environment environment.content_types().delete('content_type_id') # or if you already fetched the content type content_type.delete()
Creating a content type:
content_type_attributes = { 'name': 'Blog Post', 'description': 'Blog Posts to be included in ...', 'fields': [ { 'disabled': False, 'id': 'title', 'localized': True, 'name': 'Title', 'omitted': False, 'required': True, 'type': 'Symbol', 'validations': [ { 'size': {'min': 3} } ] }, { 'disabled': False, 'id': 'body', 'localized': True, 'name': 'Body', 'omitted': False, 'required': True, 'type': 'Text', 'validations': [] } ] } new_content_type = client.content_types('my_space_id', 'environment_id').create( 'new_ct_id', content_type_attributes ) # or if you already have a fetched environment new_content_type = environment.content_types().create( 'new_ct_id', content_type_attributes )
Updating a content type:
content_type.update(other_content_type_attributes) # or directly updating it's properties content_type.name = 'Not Post' content_type.fields.append( contentful_management.ContentTypeField({ 'id': 'author', 'name': 'Author', 'type': 'Link', 'linkType': 'Entry' }) ) content_type.save()
Deleting a content type:
client.content_types('my_space_id', 'environment_id').delete('content_type_id') # or if you already have a fetched environment environment.content_types().delete('content_type_id') # or if you already fetched the content type content_type.delete()
Publishing or Unpublishing a content type:
content_type.publish() content_type.unpublish()
Checking if a content type is published:
content_type.is_published
Checking if a content type is updated:
content_type.is_updated
Removing a field from a content type:
fields = content_type.fields # keep all fields but the one with 'author' as id content_type.fields = [ f for f in fields if not f.id == 'author' ] content_type.save()
Validations:
For information regarding available validations check the reference documentation.
Locales
Retrieving all locales on a space:
locales = client.locales('my_space_id', 'environment_id').all() # or if you already have a fetched environment locales = environment.locales().all()
Retrieveing one locale by ID:
locale = client.locales('my_space_id', 'environment_id').find('locale_id') # or if you already have a fetched environment locale = environment.locales().find('locale_id')
Deleting a locale:
client.locales('my_space_id', 'environment_id').delete('locale_id') # or if you already have a fetched environment environment.locales().delete('locale_id') # or if you already have fetched the locale locale.delete()
Creating a new locale:
new_locale = client.locales('my_space_id', 'environment_id').create({'name': 'Klingon', 'code': 'tlh'}) # or if you already have a fetched environment new_locale = environment.locales().create({'name': 'Klingon', 'code': 'tlh'})
Updating a locale:
locale.update({'name': 'Elvish'}) # or directly editing it's properties locale.name = 'Elvish' locale.save()
Roles
Retrieving all roles on a space:
roles = client.roles('my_space_id').all() # or if you already have a fetched space roles = space.roles().all()
Retrieveing one role by ID:
role = client.roles('my_space_id').find('role_id') # or if you already have a fetched space role = space.roles().find('role_id')
Deleting a role:
client.roles('my_space_id').delete('role_id') # or if you already have a fetched space space.roles().delete('role_id') # or if you already have fetched the role role.delete()
Creating a new role:
role_attributes = { 'name': 'My Role', 'description': 'foobar role', 'permissions': { 'ContentDelivery': 'all', 'ContentModel': ['read'], 'Settings': [] }, 'policies': [ { 'effect': 'allow', 'actions': 'all', 'constraint': { 'and': [ { 'equals': [ { 'doc': 'sys.type' }, 'Entry' ] }, { 'equals': [ { 'doc': 'sys.type' }, 'Asset' ] } ] } } ] } new_role = client.roles('my_space_id').create(role_attributes) # or if you already have a fetched space new_role = space.roles().create(role_attributes)
Updating a role:
roles.update({'name': 'A different Role'}) # or directly editing it's properties role.name = 'A different Role' role.save()
Webhooks
Retrieving all webhooks on a space:
webhook = client.webhooks('my_space_id').all() # or if you already have a fetched space webhook = space.webhooks().all()
Retrieveing one webhook by ID:
webhook = client.webhooks('my_space_id').find('webhook_id') # or if you already have a fetched space webhook = space.webhooks().find('webhook_id')
Deleting a webhook:
client.webhooks('my_space_id').delete('webhook_id') # or if you already have a fetched space space.webhooks().delete('webhook_id') # or if you already have fetched the webhook webhook.delete()
Creating a new webhook:
webhook_attributes = { 'name': 'My Webhook', 'url': 'https://www.example.com', 'httpBasicUsername': 'username', 'httpBasicPassword': 'password' } new_webhook = client.webhooks('my_space_id').create(webhook_attributes) # or if you already have a fetched space new_webhook = space.webhooks().create(webhook_attributes)
Updating a webhook:
webhook.update({'name': 'Other Webhook'}) # or directly editing it's properties webhook.name = 'Other Webhook' webhook.save()
Webhook Calls
Retrieving all Webhook Calls on a space:
calls = client.webhook_calls('my_space_id', 'webhook_id').all() # or if you already have a fetched webhook calls = webhook.calls().all()
Retrieveing Webhook Call Details by ID:
call = client.webhook_calls('my_space_id', 'webhook_id').find('call_id') # or if you already have a fetched webhook call = webhook.calls().find('call_id')
Webhook Health
Retrieving Webhook Health:
health = client.webhook_health('my_space_id', 'webhook_id').find() # or if you already have a fetched webhook health = webhook.health().find()
UI Extensions
Retrieving all UI Extenisons on a space:
ui_extensions = client.ui_extensions('my_space_id', 'environment_id').all() # or if you already have a fetched environment ui_extensions = environment.ui_extensions().all()
Retrieveing one UI Extension by ID:
ui_extension = client.ui_extensions('my_space_id', 'environment_id').find('ui_extension_id') # or if you already have a fetched environment ui_extension = environment.ui_extensions().find('ui_extension_id')
Deleting an UI Extension:
client.ui_extensions('my_space_id', 'environment_id').delete('ui_extension_id') # or if you already have a fetched environment environment.ui_extensions().delete('ui_extension_id') # or if you already have fetched the UI Extension ui_extension.delete()
Creating a new UI Extension:
new_ui_extension = client.ui_extensions('my_space_id', 'environment_id').create('test-extension', { "extension": { "name": "Test Extension", "srcdoc": "<html>foobar</html>", "fieldTypes": [{'type': 'Symbol'}], "sidebar": False } }) # or if you already have a fetched environment new_ui_extension = environment.ui_extensions().create('test-extension', { "extension": { "name": "Test Extension", "srcdoc": "<html>foobar</html>", "fieldTypes": [{'type': 'Symbol'}], "sidebar": False } })
Updating an UI Extension:
ui_extension.update({ "extension": { "name": "Test Extension", "srcdoc": "<html>foobar</html>", "fieldTypes": [{'type': 'Symbol'}], "sidebar": False } }) # or directly editing it's properties ui_extension.name = 'Their API Key' ui_extension.save()
Editor Interfaces
Retrieving the editor interfaces for a content type:
editor_interface = client.editor_interfaces('my_space_id', 'environment_id', 'my_content_type_id').find() # or if you already have a fetched content type editor_interface = content_type.editor_interfaces().find()
Updating the editor interface:
controls = [ { 'widgetId': 'singleLine', 'fieldId': 'name', 'settings': {} } ] editor_interface.update({'controls': controls}) # or directly editing it's properties editor_interface.controls = controls editor_interface.save()
Entry Snapshots
Retrieving all snapshots for an entry:
snapshots = client.snapshots('my_space_id', 'environment_id', 'entry_id').all() # or if you already have a fetched entry snapshots = entry.snapshots().all()
Retrieveing one snapshot by ID:
snapshot = client.snapshots('my_space_id', 'environment_id', 'entry_id').find('snapshot_id') # or if you already have a fetched entry snapshot = entry.snapshots().find('snapshot_id')
Content Type Snapshots
Retrieving all snapshots for a content type:
snapshots = client.content_type_snapshots('my_space_id', 'environment_id', 'content_type_id').all() # or if you already have a fetched content type snapshots = content_type.snapshots().all()
Retrieveing one snapshot by ID:
snapshot = client.content_type_snapshots('my_space_id', 'environment_id', 'content_type_id').find('snapshot_id') # or if you already have a fetched content_type snapshot = content_type.snapshots().find('snapshot_id')
API Keys
Retrieving all API keys on a space:
api_keys = client.api_keys('my_space_id').all() # or if you already have a fetched space api_keys = space.api_keys().all()
Retrieveing one API key by ID:
api_key = client.api_keys('my_space_id').find('api_key_id') # or if you already have a fetched space api_key = space.api_keys().find('api_key_id')
Deleting an API key:
client.api_keys('my_space_id').delete('api_key_id') # or if you already have a fetched space space.api_keys().delete('api_key_id') # or if you already have fetched the API key api_key.delete()
Creating a new API key:
new_api_key = client.api_keys('my_space_id').create({'name': 'My API Key'}) # or if you already have a fetched space new_api_key = space.api_keys().create({'name': 'My API Key'})
Creating a new API key with multiple environments:
environments = [ { "sys": { "type": "Link", "linkType": "Environment", "id": "master" } }, { "sys": { "type": "Link", "linkType": "Environment", "id": "staging" } } ] new_api_key = client.api_keys('my_space_id').create({'name': 'My API Key with environments', 'environments': environments}) # or if you already have a fetched space new_api_key = space.api_keys().create({'name': 'My API Key with environments', 'environments': environments})
Updating an API key:
api_key.update({'name': 'Their API Key'}) # or directly editing it's properties api_key.name = 'Their API Key' api_key.save()
Updating an API key with a new environment, while retaining the existing ones:
new_environment_link = Link({ "sys": { "type": "Link", "linkType": "Environment", "id": "staging" } }) api_key.environments.append(new_environment_link) api_key.save()
Preview API Keys
Retrieving all Preview API keys on a space:
preview_api_keys = client.preview_api_keys('my_space_id').all() # or if you already have a fetched space preview_api_keys = space.preview_api_keys().all()
Retrieveing one API key by ID:
preview_api_key = client.preview_api_keys('my_space_id').find('preview_api_key_id') # or if you already have a fetched space preview_api_key = space.preview_api_keys().find('preview_api_key_id') # or if you have an already fetched api key preview_api_key = api_key.preview_api_key()
Personal Access Tokens
Retrieving all Personal Access Tokens on a space:
personal_access_tokens = client.personal_access_tokens().all()
Retrieveing one Personal Access Token by ID:
personal_access_token = client.personal_access_tokens().find('personal_access_token_id')
Revoking a Personal Access Token:
client.personal_access_tokens().revoke('personal_access_token_id') # or if you already have fetched the Personal Access Token personal_access_tokens.delete()
Creating a new Personal Access Token:
new_personal_access_token = client.personal_access_tokens().create({ 'name': 'My API Key', 'scopes': ['content_management_manage'] })
Uploads
Retrieveing one upload by ID:
upload = client.uploads('my_space_id').find('upload_id') # or if you already have a fetched space upload = space.uploads().find('upload_id')
Deleting a upload:
client.uploads('my_space_id').delete('upload_id') # or if you already have a fetched space space.uploads().delete('upload_id') # or if you already have fetched the upload upload.delete()
Creating a new upload:
# you can use either a file-like object or a path. # If you use a path, the SDK will open it, create the upload and # close the file afterwards. with open('path/to/my/file.txt', 'rb') as file: new_upload = client.uploads('my_space_id').create(file) # or if you already have a fetched space new_upload = space.uploads().create('path/to/file.txt')
Associating an upload with a new asset:
# notice that the upload is converted to a link, # and the JSON representation is then sent. client.assets('my_space_id', 'environment_id').create( 'new_asset_id', { 'fields': { 'file': { 'en-US': { 'fileName': 'some_name.png', 'contentType': 'image/png', 'uploadFrom': upload.to_link().to_json() } } } } )
Client Configuration Options
access_token: API Access Token.
api_url: (optional) URL of the Contentful Target API, defaults to Management API.
uploads_api_url: (optional) URL of the Contentful Upload Target API, defaults to Upload API.
api_version: (optional) Target version of the Contentful API.
default_locale: (optional) Default Locale for your Spaces, defaults to ‘en-US’.
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 True.
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.
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.
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.
Logging
To use the logger, use the standard library logging module:
import logging logging.basicConfig(level=logging.DEBUG) client.entries().all() # INFO:requests.packages.urllib3.connectionpool:Starting new HTTPS connection (1): api.contentful.com # DEBUG:requests.packages.urllib3.connectionpool:"GET /spaces/cfexampleapi/entries HTTP/1.1" 200 1994
License
Copyright (c) 2017 Contentful GmbH. See LICENSE for details.
Contributing
Feel free to improve this tool by submitting a Pull Request.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file contentful_management-2.14.4.tar.gz
.
File metadata
- Download URL: contentful_management-2.14.4.tar.gz
- Upload date:
- Size: 70.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: pdm/2.19.2 CPython/3.10.0 Darwin/23.6.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8ab5182b8694f9f38146e4c6018afe490319747c4ea1bca3f178373c87d5a61b |
|
MD5 | 463609f5720a422af8e06b500e297f5b |
|
BLAKE2b-256 | e2cb467cd26668e870735f77e87b5d2c6efe3000ec33d8156304043031e09a8f |
File details
Details for the file contentful_management-2.14.4-py3-none-any.whl
.
File metadata
- Download URL: contentful_management-2.14.4-py3-none-any.whl
- Upload date:
- Size: 80.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: pdm/2.19.2 CPython/3.10.0 Darwin/23.6.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4eb90dab026aaa437c0fe77d3eeeb95b251ee0d6891478c9ed4e5388150b51f0 |
|
MD5 | 222b5e974441300b7f86e8941fe4393a |
|
BLAKE2b-256 | e6b46d4468904cca9931766729fa1ddb0605da3d82d73a11fd5a26b48fa19e13 |