# Stencila Types for Python
[](https://pypi.org/project/stencila_types/)
## Introduction
This package provides Python classes for types in the [Stencila Schema](https://github.com/stencila/stencila/tree/main/schema#readme), shortcuts for easily constructing these types, and utilities for loading and saving the types to JSON.
## ⚡ Usage
### Object types
Object types (aka product types) in the Stencila Schema are represented as a `dataclass`.
For example, to construct an article with a single "Hello world!" paragraph, you can construct `Article`, `Paragraph` and `Text`:
```py
from stencila_types.types import Article, CreativeWork, Paragraph, Text, Thing
article = Article(content=[Paragraph(content=[Text(value="Hello world!")])])
assert isinstance(article, Article)
assert isinstance(article, CreativeWork)
assert isinstance(article, Thing)
assert isinstance(article.content[0], Paragraph)
assert isinstance(article.content[0].content[0], Text)
```
### Union types
Union types (aka sum types) in the Stencila Schema are represented as `typing.Union`. For example, the `Block` union type is defined like so:
```py
Block = Union[
Call,
Claim,
CodeBlock,
CodeChunk,
Division,
Figure,
For,
Form,
Heading,
...
```
### Enumeration types
Enumeration types in the Stencila Schema are represented as `StrEnum`. For example, the `CitationIntent` enumeration is defined like so:
```py
class CitationIntent(StrEnum):
"""
The type or nature of a citation, both factually and rhetorically.
"""
AgreesWith = "AgreesWith"
CitesAsAuthority = "CitesAsAuthority"
CitesAsDataSource = "CitesAsDataSource"
CitesAsEvidence = "CitesAsEvidence"
CitesAsMetadataDocument = "CitesAsMetadataDocument"
CitesAsPotentialSolution = "CitesAsPotentialSolution"
CitesAsRecommendedReading = "CitesAsRecommendedReading"
CitesAsRelated = "CitesAsRelated"
```
### Shortcuts
Constructing complex Stencila types can be more easily constructed using the shortcuts module.
```py
from stencila_types import types as T
from stencila_types import shortcuts as S
# As above
art1 = T.Article(content=[T.Paragraph(content=[T.Text(value="Hello world!")])])
# Using shortcuts
art2 = S.art(S.p("Hello world!"))
assert art1 == art2
```
### Basic JSON support
```py
import json
from stencila_types.utilities import from_json, to_json
# Using shortcuts
art1 = S.art(S.p("Hello world!"))
s = to_json(art1)
assert s.startswith('{"type": "Article", "id": null,')
art2 = from_json(s)
assert art1 == art2
```
Raw data
{
"_id": null,
"home_page": null,
"name": "stencila_types",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "programmable, reproducible, interactive, documents, python, SDK",
"author": null,
"author_email": "Nokome Bentley <nokome@stencila.io>",
"download_url": "https://files.pythonhosted.org/packages/ac/47/aba6ce583af824c66b7651647ea80e5a2a1a0c752948d7352917db3d3183/stencila_types-2.0.0b2.tar.gz",
"platform": null,
"description": "# Stencila Types for Python\n\n[](https://pypi.org/project/stencila_types/)\n\n## Introduction\n\nThis package provides Python classes for types in the [Stencila Schema](https://github.com/stencila/stencila/tree/main/schema#readme), shortcuts for easily constructing these types, and utilities for loading and saving the types to JSON.\n\n## \u26a1 Usage\n\n### Object types\n\nObject types (aka product types) in the Stencila Schema are represented as a `dataclass`.\nFor example, to construct an article with a single \"Hello world!\" paragraph, you can construct `Article`, `Paragraph` and `Text`:\n\n```py\nfrom stencila_types.types import Article, CreativeWork, Paragraph, Text, Thing\n\narticle = Article(content=[Paragraph(content=[Text(value=\"Hello world!\")])])\n\nassert isinstance(article, Article)\nassert isinstance(article, CreativeWork)\nassert isinstance(article, Thing)\n\nassert isinstance(article.content[0], Paragraph)\n\nassert isinstance(article.content[0].content[0], Text)\n```\n\n### Union types\n\nUnion types (aka sum types) in the Stencila Schema are represented as `typing.Union`. For example, the `Block` union type is defined like so:\n\n```py\nBlock = Union[\n Call,\n Claim,\n CodeBlock,\n CodeChunk,\n Division,\n Figure,\n For,\n Form,\n Heading,\n...\n```\n\n### Enumeration types\n\nEnumeration types in the Stencila Schema are represented as `StrEnum`. For example, the `CitationIntent` enumeration is defined like so:\n\n```py\nclass CitationIntent(StrEnum):\n \"\"\"\n The type or nature of a citation, both factually and rhetorically.\n \"\"\"\n\n AgreesWith = \"AgreesWith\"\n CitesAsAuthority = \"CitesAsAuthority\"\n CitesAsDataSource = \"CitesAsDataSource\"\n CitesAsEvidence = \"CitesAsEvidence\"\n CitesAsMetadataDocument = \"CitesAsMetadataDocument\"\n CitesAsPotentialSolution = \"CitesAsPotentialSolution\"\n CitesAsRecommendedReading = \"CitesAsRecommendedReading\"\n CitesAsRelated = \"CitesAsRelated\"\n```\n\n### Shortcuts\n\nConstructing complex Stencila types can be more easily constructed using the shortcuts module.\n\n```py\nfrom stencila_types import types as T\nfrom stencila_types import shortcuts as S\n\n# As above\nart1 = T.Article(content=[T.Paragraph(content=[T.Text(value=\"Hello world!\")])])\n\n# Using shortcuts\nart2 = S.art(S.p(\"Hello world!\"))\n\nassert art1 == art2\n```\n\n### Basic JSON support\n\n```py\nimport json\nfrom stencila_types.utilities import from_json, to_json\n\n# Using shortcuts\nart1 = S.art(S.p(\"Hello world!\"))\n\ns = to_json(art1)\nassert s.startswith('{\"type\": \"Article\", \"id\": null,')\nart2 = from_json(s)\n\nassert art1 == art2\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python types for Stencila",
"version": "2.0.0b2",
"project_urls": {
"Homepage": "https://github.com/stencila/stencila/tree/main/python#readme",
"Repository": "https://github.com/stencila/stencila"
},
"split_keywords": [
"programmable",
" reproducible",
" interactive",
" documents",
" python",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d48ba37c3c536e337e6fcb90ae79d8e98e0c20b2de341d8a2edd9664e3c349e3",
"md5": "a1bcad599018542c0313d6e9d1fb4b8f",
"sha256": "8145ae6f06a1bbfc732c9e70552b1b16b87fdc5f7269ef185f68b9fe3958e882"
},
"downloads": -1,
"filename": "stencila_types-2.0.0b2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1bcad599018542c0313d6e9d1fb4b8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22726,
"upload_time": "2024-08-07T00:08:00",
"upload_time_iso_8601": "2024-08-07T00:08:00.151742Z",
"url": "https://files.pythonhosted.org/packages/d4/8b/a37c3c536e337e6fcb90ae79d8e98e0c20b2de341d8a2edd9664e3c349e3/stencila_types-2.0.0b2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac47aba6ce583af824c66b7651647ea80e5a2a1a0c752948d7352917db3d3183",
"md5": "b3f719459d650aa63d6c418ed8280dc9",
"sha256": "a3f5b7f0e07ebe17f7f3710affe1666ee61110637eb50b319ba91f1d785316fa"
},
"downloads": -1,
"filename": "stencila_types-2.0.0b2.tar.gz",
"has_sig": false,
"md5_digest": "b3f719459d650aa63d6c418ed8280dc9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 24613,
"upload_time": "2024-08-07T00:08:01",
"upload_time_iso_8601": "2024-08-07T00:08:01.563481Z",
"url": "https://files.pythonhosted.org/packages/ac/47/aba6ce583af824c66b7651647ea80e5a2a1a0c752948d7352917db3d3183/stencila_types-2.0.0b2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-07 00:08:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stencila",
"github_project": "stencila",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stencila_types"
}
JSON
