stencila_types 2.0.0a25__tar.gz

stencila_types-2.0.0a25/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.1
+Name: stencila_types
+Version: 2.0.0a25
+Summary: Python types for Stencila
+Keywords: programmable reproducible interactive documents python SDK
+Author-Email: Nokome Bentley <nokome@stencila.io>
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Software Development
+Classifier: License :: OSI Approved :: Apache Software License
+Project-URL: Homepage, https://github.com/stencila/stencila/tree/main/python#readme
+Project-URL: Repository, https://github.com/stencila/stencila
+Requires-Python: >=3.10
+Requires-Dist: cattrs>=23.2.3
+Requires-Dist: beartype>=0.17.2
+Requires-Dist: strenum>=0.4.15; python_version < "3.11"
+Description-Content-Type: text/markdown
+
+# stencila_types

stencila_types-2.0.0a25/README.md

@@ -0,0 +1 @@
+# stencila_types

stencila_types-2.0.0a25/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "stencila_types"
+version = "2.0.0-alpha.25"
+description = "Python types for Stencila"
+readme = "README.md"
+authors = [
+    { name = "Nokome Bentley", email = "nokome@stencila.io" },
+]
+dependencies = [
+    "cattrs>=23.2.3",
+    "beartype>=0.17.2",
+    "strenum>=0.4.15; python_version < \"3.11\"",
+]
+requires-python = ">=3.10"
+keywords = [
+    "programmable",
+    "reproducible",
+    "interactive",
+    "documents",
+    "python",
+    "SDK",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "Topic :: Software Development",
+    "License :: OSI Approved :: Apache Software License",
+]
+
+[project.license]
+text = "Apache-2.0"
+
+[project.urls]
+Homepage = "https://github.com/stencila/stencila/tree/main/python#readme"
+Repository = "https://github.com/stencila/stencila"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.dev-dependencies]
+testing = [
+    "pytest>=8.1.1",
+]
+
+[tool.pytest.ini_options]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "E",
+    "W",
+    "C90",
+    "N",
+    "UP",
+    "S",
+    "B",
+    "A",
+    "C4",
+    "PIE",
+    "ISC",
+    "T20",
+    "PT",
+    "RET",
+    "SIM",
+    "PTH",
+    "Q",
+    "PLR",
+    "PLE",
+    "I001",
+]
+ignore = [
+    "N812",
+]
+unfixable = [
+    "T20",
+    "F841",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/stencila_types/types.py" = [
+    "E501",
+]
+"tests/**" = [
+    "S101",
+]
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+]
+pythonVersion = "3.10"
+venvPath = "."
+venv = ".venv"

stencila_types-2.0.0a25/src/stencila_types/shortcuts.py

@@ -0,0 +1,360 @@
+from collections.abc import Iterable
+from typing import Optional, TypeAlias, Union
+
+from beartype import beartype
+
+from stencila_types import types as T  # noqa: N812
+
+# Our convertible type handles anything that is iterable (lists, tuples,
+# generators etc.)
+
+ConvertibleToInline: TypeAlias = str | T.Inline | Iterable[T.Inline | str]
+ConvertibleToBlocks: TypeAlias = str | T.Block | Iterable[T.Block | str]
+
+
+def flatten(args):
+    """This makes our job much easier by normalising everything to an iterable."""
+    if isinstance(args, str) or not isinstance(args, Iterable):
+        yield args
+    else:
+        for elem in args:
+            yield from flatten(elem)
+
+
+@beartype
+def convert_to_inlines(args: ConvertibleToInline):
+    return [T.Text(value=arg) if isinstance(arg, str) else arg for arg in flatten(args)]
+
+
+@beartype
+def convert_to_blocks(args: ConvertibleToBlocks):
+    return [
+        T.Paragraph(content=[T.Text(value=arg)]) if isinstance(arg, str) else arg
+        for arg in flatten(args)
+    ]
+
+
+@beartype
+def aud(url: str) -> T.AudioObject:
+    return T.AudioObject(content_url=url)
+
+
+# Force keywords, otherwise it is ambiguous
+@beartype
+def btn(*, name: str, code: str) -> T.Button:
+    return T.Button(name=name, code=code)
+
+
+@beartype
+def ct(target: str):
+    return T.Cite(target=target, citation_mode=T.CitationMode.Parenthetical)
+
+
+@beartype
+def ctg(targets: Iterable[str]):
+    return T.CiteGroup(items=[ct(t) for t in targets])
+
+
+@beartype
+def ce(code: str, *, lang: str | None = None) -> T.CodeExpression:
+    return T.CodeExpression(code=code, programming_language=lang)
+
+
+@beartype
+def ci(code: str):
+    return T.CodeInline(code=code)
+
+
+@beartype
+def dei(content: ConvertibleToInline) -> T.DeleteInline:
+    return T.DeleteInline(content=convert_to_inlines(content))
+
+
+@beartype
+def em(content: str | T.Text) -> T.Emphasis:
+    # Emphasis actually takes a list, but if these are shortcuts...
+    if isinstance(content, str):
+        content = T.Text(value=content)
+    return T.Emphasis(content=[content])
+
+
+@beartype
+def img(url: str) -> T.ImageObject:
+    return T.ImageObject(content_url=url)
+
+
+@beartype
+def isi(content: ConvertibleToInline) -> T.InsertInline:
+    return T.InsertInline(content=convert_to_inlines(content))
+
+
+@beartype
+def lnk(content: ConvertibleToInline, target: str) -> T.Link:
+    return T.Link(content=convert_to_inlines(content), target=target)
+
+
+@beartype
+def mi(code: str, *, lang: str | None = None) -> T.MathInline:
+    return T.MathInline(code=code, math_language=lang)
+
+
+@beartype
+def nte(note_type: T.NoteType, content: ConvertibleToBlocks) -> T.Note:
+    return T.Note(note_type=note_type, content=convert_to_blocks(content))
+
+
+@beartype
+def par(name: str) -> T.Parameter:
+    return T.Parameter(name=name)
+
+
+@beartype
+def rei(
+    content: ConvertibleToInline, replacement: ConvertibleToInline
+) -> T.ReplaceInline:
+    return T.ReplaceInline(
+        content=convert_to_inlines(content),
+        replacement=convert_to_inlines(replacement),
+    )
+
+
+@beartype
+def qi(content: ConvertibleToInline) -> T.QuoteInline:
+    return T.QuoteInline(content=convert_to_inlines(content))
+
+
+@beartype
+def sti(code: str, content: ConvertibleToInline) -> T.StyledInline:
+    return T.StyledInline(code=code, content=convert_to_inlines(content))
+
+
+@beartype
+def stk(content: ConvertibleToInline) -> T.Strikeout:
+    return T.Strikeout(content=convert_to_inlines(content))
+
+
+@beartype
+def stg(content: ConvertibleToInline) -> T.Strong:
+    return T.Strong(content=convert_to_inlines(content))
+
+
+@beartype
+def sub(content: ConvertibleToInline) -> T.Subscript:
+    return T.Subscript(content=convert_to_inlines(content))
+
+
+@beartype
+def sup(content: ConvertibleToInline) -> T.Superscript:
+    return T.Superscript(content=convert_to_inlines(content))
+
+
+@beartype
+def t(content: str) -> T.Text:
+    return T.Text(value=str(content))
+
+
+@beartype
+def u(content: ConvertibleToInline) -> T.Underline:
+    return T.Underline(content=convert_to_inlines(content))
+
+
+@beartype
+def adm(
+    admonition_type: T.AdmonitionType,
+    content: ConvertibleToBlocks,
+    *,
+    title: str | None = None,
+) -> T.Admonition:
+    return T.Admonition(
+        admonition_type=admonition_type,
+        content=convert_to_blocks(content),
+        title=convert_to_inlines(title),
+    )
+
+
+@beartype
+def clb(source: str, args: list[T.CallArgument]) -> T.CallBlock:
+    return T.CallBlock(source=source, arguments=args)
+
+
+@beartype
+def arg(name: str, code: str) -> T.CallArgument:
+    return T.CallArgument(name=name, code=code)
+
+
+@beartype
+def clm(claim_type: T.ClaimType, content: ConvertibleToBlocks) -> T.Claim:
+    return T.Claim(
+        claim_type=claim_type,
+        content=convert_to_blocks(content),
+    )
+
+
+@beartype
+def cb(code: str, *, lang: str | None = None) -> T.CodeBlock:
+    return T.CodeBlock(code=code, programming_language=lang)
+
+
+@beartype
+def cc(code: str, *, lang: str | None = None) -> T.CodeChunk:
+    return T.CodeChunk(code=code, programming_language=lang)
+
+
+@beartype
+def deb(content: ConvertibleToBlocks) -> T.DeleteBlock:
+    return T.DeleteBlock(content=convert_to_blocks(content))
+
+
+@beartype
+def fig(content: ConvertibleToBlocks) -> T.Figure:
+    return T.Figure(content=convert_to_blocks(content))
+
+
+@beartype
+def frb(code: str, variable: str, content: ConvertibleToBlocks) -> T.ForBlock:
+    return T.ForBlock(code=code, variable=variable, content=convert_to_blocks(content))
+
+
+@beartype
+def h(level: int, content: ConvertibleToInline):
+    return T.Heading(level=level, content=convert_to_inlines(content))
+
+
+@beartype
+def h1(content: ConvertibleToInline) -> T.Heading:
+    return h(1, content)
+
+
+@beartype
+def h2(content: ConvertibleToInline) -> T.Heading:
+    return h(2, content)
+
+
+@beartype
+def h3(content: ConvertibleToInline) -> T.Heading:
+    return h(3, content)
+
+
+@beartype
+def h4(content: ConvertibleToInline) -> T.Heading:
+    return h(4, content)
+
+
+@beartype
+def h5(content: ConvertibleToInline) -> T.Heading:
+    return h(5, content)
+
+
+@beartype
+def h6(content: ConvertibleToInline) -> T.Heading:
+    return h(6, content)
+
+
+@beartype
+def ifb(clauses: list[T.IfBlockClause]) -> T.IfBlock:
+    return T.IfBlock(clauses=clauses)
+
+
+@beartype
+def ibc(
+    code: str, content: ConvertibleToBlocks, *, lang: str | None = None
+) -> T.IfBlockClause:
+    return T.IfBlockClause(
+        code=code, programming_language=lang, content=convert_to_blocks(content)
+    )
+
+
+@beartype
+def inb(source: str) -> T.IncludeBlock:
+    return T.IncludeBlock(source=source)
+
+
+@beartype
+def isb(content: ConvertibleToBlocks) -> T.InsertBlock:
+    return T.InsertBlock(content=convert_to_blocks(content))
+
+
+@beartype
+def ol(items: list[T.ListItem]) -> T.List:
+    return T.List(items=items, order=T.ListOrder.Ascending)
+
+
+@beartype
+def ul(items: list[T.ListItem]) -> T.List:
+    return T.List(items=items, order=T.ListOrder.Unordered)
+
+
+@beartype
+def li(content: ConvertibleToBlocks) -> T.ListItem:
+    return T.ListItem(content=convert_to_blocks(content))
+
+
+@beartype
+def mb(code: str, *, lang: str | None = None) -> T.MathBlock:
+    return T.MathBlock(code=code, math_language=lang)
+
+
+@beartype
+def p(*args: ConvertibleToInline) -> T.Paragraph:
+    return T.Paragraph(content=convert_to_inlines(args))
+
+
+@beartype
+def qb(content: ConvertibleToBlocks) -> T.QuoteBlock:
+    return T.QuoteBlock(content=convert_to_blocks(content))
+
+
+@beartype
+def reb(
+    content: ConvertibleToBlocks, replacement: ConvertibleToBlocks
+) -> T.ReplaceBlock:
+    return T.ReplaceBlock(
+        content=convert_to_blocks(content),
+        replacement=convert_to_blocks(replacement),
+    )
+
+
+@beartype
+def sec(content: ConvertibleToBlocks) -> T.Section:
+    return T.Section(content=convert_to_blocks(content))
+
+
+@beartype
+def stb(style: str, content: ConvertibleToBlocks) -> T.StyledBlock:
+    return T.StyledBlock(code=style, content=convert_to_blocks(content))
+
+
+@beartype
+def tbl(rows: list[T.TableRow]) -> T.Table:
+    return T.Table(rows=rows)
+
+
+@beartype
+def tr(cells: list[T.TableCell]) -> T.TableRow:
+    return T.TableRow(cells=cells)
+
+
+@beartype
+def th(content: ConvertibleToBlocks) -> T.TableCell:
+    return T.TableCell(
+        content=convert_to_blocks(content),
+        cell_type=T.TableCellType.HeaderCell,
+    )
+
+
+@beartype
+def td(content: ConvertibleToBlocks) -> T.TableCell:
+    return T.TableCell(
+        content=convert_to_blocks(content),
+        cell_type=T.TableCellType.DataCell,
+    )
+
+
+@beartype
+def tb() -> T.ThematicBreak:
+    return T.ThematicBreak()
+
+
+@beartype
+def art(content: ConvertibleToBlocks) -> T.Article:
+    return T.Article(content=convert_to_blocks(content))