Skip to main content

A Python toolkit for Contentful to let you create/maintain your Content Type and queries in ORM style.

Project description


A Python toolkit for Contentful to let you create/maintain your Content Type and queries in ORM style.


  • To install:
    pip install git+


ORM Environment

  • Create an ORM Environment:
    import contentful_management
    from contentful_orm import ORMEnvironment
    # First create an contentful_management.environment.Environment
    client = contentful_management.Client('CONTENTFUL_MANAGEMENT_TOKEN')
    space = client.spaces().find('CONTENTFUL_SPACE_ID')
    environment = space.environments().find('CONTENTFUL_ENVIRONMENT')
    # Then create ORMEnvironment use contentful_management.environment.Environment
    orm_env = ORMEnvironment.from_parent(environment)

Content Type Model

  • Model your content type:
    from datetime import datetime
    from contentful_orm.models import Model
    from contentful_orm.fields import ArrayField, BooleanField, DateField, DecimalField, IntegerField, MediaField, ReferenceField, SymbolField, TextField, LocationField
    from contentful_orm.fields.validations import In, Range, Unique, Size, Regex, ImageDimensions, FileSize
    # class name will become content type name
    # class name in camel case will become content type id
    class Person(Model):
        # docstring will become content type description
        """Person model description
        __display_field__ = 'name'
        # Each field need to be a {SomeType}Field from contentful_orm.fields
        # Most of the fields have keyword argument: disabled, localized, omitted, required, validations and default
        # (disabled, localized, omitted and required default to False. validations defaults to []. default defaults to None)
        email = SymbolField(validations=[Unique, Regex('^\\w[\\w.-]*@([\\w-]+\\.)+[\\w-]+$', error_msg='Invalid email address.')], required=True)
        name = SymbolField(localized=True, required=True)
        # ArrayField takes an argument to specify content type
        title = ArrayField(SymbolField(validations=[In(['Manager', 'Seller'], error_msg='Invalid title')]), localized=True)
        age = IntegerField(validations=[Range(min=1, error_msg='age must be a positive integer.')])
        created_date = DateField("%Y-%m-%dT%H:%M-00:00"))
    class Company(Model):
        """Company model description
        __display_field__ = 'name'
        name = SymbolField(validations=[Unique], required=True)
        employees = ArrayField(ReferenceField(model_set={Person}, error_msg='employee has to be a Person entry'))
        address = LocationField()
    class Product(Model):
        """Product model description
        __display_field__ = 'name'
        name = SymbolField(validations=[Unique], required=True)
        description = TextField(localized=True)
        # ReferenceField takes an additional keyword argument model_set to restrict reference content type.
        # (Currently doesn't support reference to the content type itself)
        seller = ReferenceField(model_set={Person, Company}, error_msg="seller has to be a Person or Company entry")
        images = ArrayField(
                # validations takes a list of contentful_orm.fields.validations
                # See: for details
                    ImageDimensions(max_width=12, max_height=12),
                    FileSize(max=40000, error_msg='Maximum file size is 40000 Bytes')
            validations=[Size(max=10, error_msg="At most 10 images")]
        sponsored = BooleanField(required=True)
        price = DecimalField(required=True)
  • Create and publish the content type using model:
    # Or
  • Unpublish and delete the content type using model:
  • Add and publish entry:
    person1 = orm_env.add(Person(email='', name='a', title=['Manager', 'Seller'], age=13)).publish()
    # You can specify entry id or it will randomly generate a UUID
    person2 = orm_env.add(Person(email='', name='b', title=['Seller'], age=66), id='S9SN3JWKN3565D').publish()
    person3 = orm_env.add(Person(email='', name='c', title=['Manager'], created_date='2019-08-11T00:00-07:00')).publish()
    company1 = orm_env.add(Company(name='Contentful', employees=[person1.to_link().to_json(), person2.to_link().to_json()])).publish()
    # Or
    product1 = Product(
        description='Write your Contentful in ORM style!',
  • Query:
    # Query all entries of a content type
    # Filter query
    # ORMContentTypeEntriesProxy extends ContentTypeEntriesProxy with additional filter function
    from contentful_orm.operators import all_, limit, select, skip
    # Filter with field names as keyword arguments for exact search
    orm_env.query(Person).filter(email='', name='c')
    # Filter with operators, see operators all at:
    orm_env.query(Person).filter(all_(title=['Manager', 'seller']), skip(1), limit(100), select(''))
    # Use combination of both
    orm_env.query(Person).filter(limit(1), name='c')
  • Serialize:
    from contentful_orm.serializers import ModelSerializer
    class ProductSerializer(ModelSerializer):
        class Meta:
            model = Product
            # Specify fields to be serialized or use '__all__' for all the fields
            fields = [
    # Query the entry/entries you want to serialize
    products = orm_env.query(Product).all()
    # Serialize single entry
    serialized_product = ProductSerializer(products[0])
    # Serialize multiple entries
    serialized_products = ProductSerializer(products, many=True)
    # Currently links won't be recursively serialized, in case of circular references.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

contentful_orm-0.1.0.tar.gz (11.0 kB view hashes)

Uploaded source

Built Distribution

contentful_orm-0.1.0-py3-none-any.whl (12.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page