nthp_api 0.1.9__tar.gz

nthp_api-0.1.9/LICENCE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2021 The Nottingham New Theatre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nthp_api-0.1.9/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: nthp_api
+Version: 0.1.9
+Summary: This is a CLI tool for building the Nottingham New Theatre's History Project content database.
+License: MIT
+License-File: LICENCE
+Author: Will Pimblett
+Author-email: will@wjdp.uk
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: Markdown (>=3.4.3,<4.0.0)
+Requires-Dist: PyYAML (>=6.0,<7.0)
+Requires-Dist: click (>=8.1.3,<9.0.0)
+Requires-Dist: coloredlogs (>=15.0.1,<16.0.0)
+Requires-Dist: httpx (>=0.24.1,<0.25.0)
+Requires-Dist: peewee (>=3.16.2,<4.0.0)
+Requires-Dist: pydantic (>=2.1.1,<3.0.0)
+Requires-Dist: pydantic-collections (>=0.5.0,<0.6.0)
+Requires-Dist: pydantic-settings (>=2.0.2,<3.0.0)
+Requires-Dist: pyhumps (>=3.8.0,<4.0.0)
+Requires-Dist: python-frontmatter (>=1.0.0,<2.0.0)
+Requires-Dist: python-slugify (>=8.0.1,<9.0.0)
+Project-URL: Homepage, https://github.com/newtheatre/nthp-api
+Project-URL: Repository, https://github.com/newtheatre/nthp-api
+Description-Content-Type: text/markdown
+
+# History Project API Generator
+
+This project generates a JSON API from the [history-project](https://github.com/newtheatre/history-project) content repository. It does that in two steps:
+
+- **load**: Generate a sqlite database from the source files.
+- **dump**: Use that database to generate a JSON API.
+
+## Endpoints
+
+- The API is currently hosted at <https://nthp-api.wjdp.uk/v1>.
+- The specification is available at <https://nthp-api.wjdp.uk/v1/master/openapi.json>.
+- To render the spec into human-readable docs use a tool such as:
+  - ReDoc <https://redocly.github.io/redoc/?url=https://nthp-api.wjdp.uk/v1/master/openapi.json>.
+  - Stoplight <https://elements-demo.stoplight.io/?spec=https://nthp-api.wjdp.uk/v1/master/openapi.json>
+
+# Usage
+
+## From source
+
+- Ensure you have [Poetry](https://python-poetry.org/) installed.
+- Run `poetry install`.
+- Clone the history project repository into the `content/` directory. You can do a shallow clone for this: `GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 --branch master git@github.com:newtheatre/history-project content`.
+- Run `./nthp load` to generate the sqlite database from the content files.
+- Run `./nthp dump` to generate the API from the database into the `dist/` directory.
+
+## From PyPi
+
+- With pip installed run `pip install --user nthp-api`. If you have your local bin folder on your path you should now be able to run `nthp`.
+- Within the history-project repo run `nthp load` to generate the sqlite database from the content files.
+- Run `nthp dump` to generate the API from the database into the `dist/` directory.
+
+Alternatively you can run `nthp build` to run both steps in one go.
+
+## Contributing
+
+### pre-commit hooks
+
+pre-commit hooks are used to lint the source code using [Black](https://black.readthedocs.io/en/stable/) and [ruff](https://ruff.rs)
+
+- Ensure you have [pre-commit](https://pre-commit.com/) installed.
+- Run `pre-commit install` to install pre-commit hooks.
+
+### Tests
+
+Run `pytest` or use the included PyCharm run configuration.
+
+## Release
+
+See the `bin/release.sh` script for the release process. This assumes that your local machine has the correct credentials to publish to PyPi.
+

nthp_api-0.1.9/README.md

@@ -0,0 +1,49 @@
+# History Project API Generator
+
+This project generates a JSON API from the [history-project](https://github.com/newtheatre/history-project) content repository. It does that in two steps:
+
+- **load**: Generate a sqlite database from the source files.
+- **dump**: Use that database to generate a JSON API.
+
+## Endpoints
+
+- The API is currently hosted at <https://nthp-api.wjdp.uk/v1>.
+- The specification is available at <https://nthp-api.wjdp.uk/v1/master/openapi.json>.
+- To render the spec into human-readable docs use a tool such as:
+  - ReDoc <https://redocly.github.io/redoc/?url=https://nthp-api.wjdp.uk/v1/master/openapi.json>.
+  - Stoplight <https://elements-demo.stoplight.io/?spec=https://nthp-api.wjdp.uk/v1/master/openapi.json>
+
+# Usage
+
+## From source
+
+- Ensure you have [Poetry](https://python-poetry.org/) installed.
+- Run `poetry install`.
+- Clone the history project repository into the `content/` directory. You can do a shallow clone for this: `GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 --branch master git@github.com:newtheatre/history-project content`.
+- Run `./nthp load` to generate the sqlite database from the content files.
+- Run `./nthp dump` to generate the API from the database into the `dist/` directory.
+
+## From PyPi
+
+- With pip installed run `pip install --user nthp-api`. If you have your local bin folder on your path you should now be able to run `nthp`.
+- Within the history-project repo run `nthp load` to generate the sqlite database from the content files.
+- Run `nthp dump` to generate the API from the database into the `dist/` directory.
+
+Alternatively you can run `nthp build` to run both steps in one go.
+
+## Contributing
+
+### pre-commit hooks
+
+pre-commit hooks are used to lint the source code using [Black](https://black.readthedocs.io/en/stable/) and [ruff](https://ruff.rs)
+
+- Ensure you have [pre-commit](https://pre-commit.com/) installed.
+- Run `pre-commit install` to install pre-commit hooks.
+
+### Tests
+
+Run `pytest` or use the included PyCharm run configuration.
+
+## Release
+
+See the `bin/release.sh` script for the release process. This assumes that your local machine has the correct credentials to publish to PyPi.

nthp_api-0.1.9/nthp_api/cli/__init__.py

@@ -0,0 +1,88 @@
+import logging
+from os import environ
+
+import click
+
+from nthp_api.cli import logs
+from nthp_api.nthp_build.version import get_version
+
+logs.init()
+
+
+log = logging.getLogger(__name__)
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def version():
+    print(f"nthp-api {get_version()}")  # noqa T201
+
+
+@click.argument("path", type=click.Path(exists=True))
+@cli.command()
+def load(path):
+    environ["CONTENT_ROOT"] = str(path)
+
+    from nthp_api.nthp_build import database, loader
+
+    database.init_db(create=True)
+    loader.run_loaders()
+
+
+@cli.command()
+def stats():
+    environ["CONTENT_ROOT"] = "does-not-matter"
+
+    from nthp_api.nthp_build import database
+
+    database.init_db()
+    database.show_stats()
+
+
+@cli.command()
+def smug():
+    environ["CONTENT_ROOT"] = "does-not-matter"
+
+    import nthp_api.smugmugger.database
+    from nthp_api.nthp_build import database, smugmug
+
+    database.init_db()
+    nthp_api.smugmugger.database.init_db()
+    smugmug.run()
+
+
+@cli.command()
+def dump():
+    environ["CONTENT_ROOT"] = "does-not-matter"
+
+    from nthp_api.nthp_build import database, dumper
+
+    database.init_db()
+    dumper.delete_output_dir()
+    dumper.dump_all()
+
+
+@click.argument("path", type=click.Path(exists=True))
+@cli.command()
+def build(path):
+    # Set settings using environment variables as workers and threads will recreate
+    # the settings object and not pick up the values if set here.
+    environ["DB_URI"] = ":memory:"
+    environ["CONTENT_ROOT"] = str(path)
+
+    log.info(f"Building from {path} using in-memory database")
+
+    import nthp_api.smugmugger.database
+    from nthp_api.nthp_build import database, dumper, loader, smugmug
+
+    database.init_db(create=True)
+    loader.run_loaders()
+    database.show_stats()
+    nthp_api.smugmugger.database.init_db()
+    smugmug.run()
+    dumper.delete_output_dir()
+    dumper.dump_all()

nthp_api-0.1.9/nthp_api/cli/logs.py

@@ -0,0 +1,20 @@
+import logging
+from os import environ
+
+import coloredlogs
+
+LOG_FORMAT = "%(asctime)s %(levelname)s %(message)s"
+DATE_FORMAT = "%H:%M:%S"
+
+
+def init():
+    nthp_build_logger = logging.getLogger("nthp_api.nthp_build")
+    smugmugger_logger = logging.getLogger("nthp_api.smugmugger")
+
+    log_level = environ.get("LOG_LEVEL", "INFO")
+    coloredlogs.install(
+        level=log_level, logger=nthp_build_logger, fmt=LOG_FORMAT, datefmt=DATE_FORMAT
+    )
+    coloredlogs.install(
+        level=log_level, logger=smugmugger_logger, fmt=LOG_FORMAT, datefmt=DATE_FORMAT
+    )

nthp_api-0.1.9/nthp_api/nthp_build/assets.py

@@ -0,0 +1,229 @@
+import json
+import logging
+import mimetypes
+from collections.abc import Generator, Iterable
+from enum import Enum
+
+from nthp_api.nthp_build import database, models, schema
+from nthp_api.nthp_build.documents import DocumentPath
+from nthp_api.smugmugger import SmugMugImage
+
+log = logging.getLogger(__name__)
+
+
+class AssetTarget(database.DbCompatEnumMixin, Enum):
+    SHOW = "show"
+    PERSON = "person"
+    VENUE = "venue"
+    ALBUM = "album"
+
+
+class AssetSource(database.DbCompatEnumMixin, Enum):
+    SMUGMUG = "smugmug"
+    FILE = "file"
+
+
+class AssetType(database.DbCompatEnumMixin, Enum):
+    ALBUM = "album"  # A collection of other assets
+    IMAGE = "image"  # A single image, a photo or a scanned document
+    VIDEO = "video"  # A video
+    OTHER = "other"  # A video
+
+
+class AssetCategory(database.DbCompatEnumMixin, Enum):
+    POSTER = "poster"
+    FLYER = "flyer"
+    PROGRAMME = "programme"
+    HEADSHOT = "headshot"
+
+
+def get_mime_type(source: AssetSource, type: AssetType, id: str) -> str | None:
+    """
+    Decide or determine the mime-type of an asset.
+    :param source: Where does this asset come from?
+    :param type: Type of asset
+    :param id:
+    :return: A mime type, or None if either we can't determine one or one does not apply
+    """
+    if source is AssetSource.SMUGMUG:
+        if type is AssetType.ALBUM:
+            return None
+        if type is AssetType.IMAGE:
+            return "image/jpeg"
+        if type is AssetType.VIDEO:
+            return "video/mp4"  # TODO: check if correct
+        raise ValueError(f"Unhandled asset type {type}")
+
+    if source is AssetSource.FILE:
+        guess = mimetypes.guess_type(id)[0]
+        if guess is None:
+            raise ValueError(f"Could not guess mime type for {id}")
+        return guess
+
+    raise ValueError(f"Unhandled asset source {source}")
+
+
+def save_asset(  # noqa: PLR0913
+    target_id: str,
+    target_type: AssetTarget,
+    source: AssetSource,
+    type: AssetType,
+    id: str,
+    category: AssetCategory | str | None = None,
+    title: str | None = None,
+    page: int | None = None,
+) -> database.Asset:
+    return database.Asset.create(
+        target_id=target_id,
+        target_type=target_type,
+        asset_source=source,
+        asset_type=type,
+        asset_mime_type=get_mime_type(source, type, id),
+        asset_id=id,
+        asset_category=category,
+        title=title,
+        page=page,
+    )
+
+
+def assets_from_show_model(
+    show: models.Show,
+) -> Generator[schema.Asset, None, None]:
+    """Generate show assets (output type) from a show model (input type)"""
+    for asset in show.assets:
+        if asset.image:
+            source = AssetSource.SMUGMUG
+            type = AssetType.IMAGE
+        elif asset.video:
+            source = AssetSource.SMUGMUG
+            type = AssetType.VIDEO
+        elif asset.filename:
+            source = AssetSource.FILE
+            # We assume files are something else, but could be image or video.
+            # In reality they tend to be PDF / audio / other docs
+            type = AssetType.OTHER
+        else:
+            raise ValueError(f"Unhandled mode for asset {asset}")
+
+        asset_id = asset.image or asset.video or asset.filename
+        if not asset_id:
+            raise ValueError(f"No ID for asset {asset}")
+
+        yield schema.Asset(
+            type=str(type),
+            source=str(source),
+            mime_type=get_mime_type(source, type, asset_id),
+            id=asset_id,
+            category=asset.type,
+            # we use type for image/video/other, source uses it for category
+            title=asset.title,
+            page=asset.page,
+        )
+
+    if show.prod_shots:
+        yield schema.Asset(
+            type=str(AssetType.ALBUM),
+            source=str(AssetSource.SMUGMUG),
+            mime_type=get_mime_type(
+                AssetSource.SMUGMUG, AssetType.ALBUM, show.prod_shots
+            ),
+            id=show.prod_shots,
+        )
+
+
+def save_show_assets(
+    path: DocumentPath, show_assets: Iterable[schema.Asset]
+) -> list[database.Asset]:
+    """Write assets to the database"""
+    return [
+        save_asset(
+            target_id=path.id,
+            target_type=AssetTarget.SHOW,
+            source=AssetSource(asset.source),
+            type=AssetType(asset.type),
+            id=asset.id,
+            category=asset.category,
+            title=asset.title,
+            page=asset.page,
+        )
+        for asset in show_assets
+    ]
+
+
+def save_person_assets(
+    path: DocumentPath, person: models.Person
+) -> list[database.Asset]:
+    assets = []
+    if person.headshot:
+        assets.append(
+            save_asset(
+                target_id=path.id,
+                target_type=AssetTarget.PERSON,
+                source=AssetSource.SMUGMUG,
+                type=AssetType.IMAGE,
+                id=person.headshot,
+                category=AssetCategory.HEADSHOT,
+                title=person.title,
+            )
+        )
+    return assets
+
+
+def filter_assets_by_type(assets, type):
+    return list(filter(lambda asset: asset.type.lower() == type.value, assets))
+
+
+def pick_show_primary_image(assets: list[models.Asset]) -> str | None:
+    """
+    Pick an image to use as the primary, to be used in list views &c
+    TODO: Currently we return a SmugMug ID rather than a full Asset object.
+    """
+    image_assets = list(filter(lambda asset: asset.image is not None, assets))
+    if override_assets := list(filter(lambda asset: asset.display_image, image_assets)):
+        return override_assets[0].image
+    if posters := filter_assets_by_type(image_assets, AssetCategory.POSTER):
+        return posters[0].image
+    if flyers := filter_assets_by_type(image_assets, AssetCategory.FLYER):
+        return flyers[0].image
+    if programmes := filter_assets_by_type(image_assets, AssetCategory.PROGRAMME):
+        return programmes[0].image
+    # No suitable image found, oh well we tried
+    return None
+
+
+def smugmug_asset_to_asset(smugmug_asset: SmugMugImage) -> schema.Asset:
+    """Convert a SmugMug asset to a schema asset"""
+    asset_type = AssetType.VIDEO if smugmug_asset.IsVideo else AssetType.IMAGE
+    return schema.Asset(
+        id=smugmug_asset.ImageKey,
+        source=AssetSource.SMUGMUG.value,
+        title=smugmug_asset.Title or None,
+        type=asset_type.value,
+        mime_type=get_mime_type(
+            AssetSource.SMUGMUG, asset_type, smugmug_asset.ImageKey
+        ),
+    )
+
+
+def get_asset_collection_from_album(
+    album: database.Asset,
+) -> schema.AssetCollection | None:
+    """
+    Get AssetCollection from an asset album.
+    Currently, we only support SmugMug albums.
+    If the SmugMug data isn't present or fails to parse, we return None.
+    """
+    if album.asset_source != AssetSource.SMUGMUG.value:
+        raise ValueError(f"Album source '{album.asset_source}' unsupported")
+    if not album.asset_smugmug_data:
+        log.warning(f"No smugmug data for album {album.asset_id}")
+        return None
+    try:
+        smugmug_album_images = json.loads(album.asset_smugmug_data)
+        smugmug_assets = [SmugMugImage(**asset) for asset in smugmug_album_images]
+    except json.JSONDecodeError:
+        log.warning(f"Could not decode smugmug data for album {album.asset_id}")
+        return None
+    return schema.AssetCollection(
+        [smugmug_asset_to_asset(asset) for asset in smugmug_assets]
+    )

nthp_api-0.1.9/nthp_api/nthp_build/config.py

@@ -0,0 +1,22 @@
+import datetime
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    db_uri: str = "nthp.db"
+    branch: str = "master"
+    content_root: Path
+
+    year_start: int = 1940
+    year_end: int = datetime.datetime.now().year
+
+    # How many years to wait until guessing someone has left, if it's not been this
+    # long we can assume they may still be a student.
+    graduation_recency_limit: int = 2
+    # What month (1-12) do people tend to graduate in?
+    graduation_month: int = 6
+
+
+settings = Settings()

nthp_api-0.1.9/nthp_api/nthp_build/content.py

@@ -0,0 +1,39 @@
+from io import StringIO
+
+import markdown
+from markdown import Markdown
+
+
+def unmark_element(element, stream=None):
+    if stream is None:
+        stream = StringIO()
+    if element.text:
+        stream.write(element.text)
+    for sub in element:
+        unmark_element(sub, stream)
+    if element.tail:
+        stream.write(element.tail)
+    return stream.getvalue()
+
+
+# Make a markdown parser that outputs plaintext
+# Stole from https://stackoverflow.com/a/54923798/1345360
+Markdown.output_formats["plain"] = unmark_element  # type: ignore
+_markdown_unmarker = Markdown(output_format="plain")  # type: ignore
+_markdown_unmarker.stripTopLevelTags = False  # type: ignore
+
+
+def markdown_to_html(markdown_text: str | None) -> str | None:
+    if not markdown_text:
+        return None
+    if not markdown_text.strip():
+        return None
+    return markdown.markdown(markdown_text)
+
+
+def markdown_to_plaintext(markdown_text: str | None) -> str | None:
+    if not markdown_text:
+        return None
+    if not markdown_text.strip():
+        return None
+    return _markdown_unmarker.convert(markdown_text)