# 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/58/0d/7e7910ed2d0d96808881fcf748ddfbf822a9dadc48613b8f030e56c19432/stencila_types-2.0.0a28.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.0a28",
"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": "90b3e7bfc5c6c841ea1b01565ddaaf304ab95c938271b8dbe6b05d3e71218cc2",
"md5": "9986f3a4037e89a15f8786313adff722",
"sha256": "06bdc54ac90c929865faa43fa991707a2da91200c6365e7cfc16fa30feb1035e"
},
"downloads": -1,
"filename": "stencila_types-2.0.0a28-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9986f3a4037e89a15f8786313adff722",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 21141,
"upload_time": "2024-03-25T10:05:50",
"upload_time_iso_8601": "2024-03-25T10:05:50.675715Z",
"url": "https://files.pythonhosted.org/packages/90/b3/e7bfc5c6c841ea1b01565ddaaf304ab95c938271b8dbe6b05d3e71218cc2/stencila_types-2.0.0a28-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "580d7e7910ed2d0d96808881fcf748ddfbf822a9dadc48613b8f030e56c19432",
"md5": "61a0255f1ca06dca022cd13a964ceb21",
"sha256": "c52404a7e9fae6a3bb20e00d20a9e4db8b6fc8cfc79736114312ddbf8aba8db1"
},
"downloads": -1,
"filename": "stencila_types-2.0.0a28.tar.gz",
"has_sig": false,
"md5_digest": "61a0255f1ca06dca022cd13a964ceb21",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22871,
"upload_time": "2024-03-25T10:05:52",
"upload_time_iso_8601": "2024-03-25T10:05:52.547137Z",
"url": "https://files.pythonhosted.org/packages/58/0d/7e7910ed2d0d96808881fcf748ddfbf822a9dadc48613b8f030e56c19432/stencila_types-2.0.0a28.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 10:05:52",
"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
