betty.extension package - Betty documentation

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# betty.extension package

## Subpackages

- betty.extension.cotton_candy package
  - Submodules
    - betty.extension.cotton_candy.gui module
    - betty.extension.cotton_candy.search module
      - `Index`
        - `Index.__init__()`
        - `Index.build()`
  - Module contents
    - `CottonCandy`
      - `CottonCandy.assets_directory_path()`
      - `CottonCandy.comes_after()`
      - `CottonCandy.default_configuration()`
      - `CottonCandy.depends_on()`
      - `CottonCandy.description()`
      - `CottonCandy.filters`
      - `CottonCandy.generate()`
      - `CottonCandy.globals`
      - `CottonCandy.gui_build()`
      - `CottonCandy.label()`
      - `CottonCandy.logo`
      - `CottonCandy.name()`
      - `CottonCandy.public_css_paths`
      - `CottonCandy.webpack_entry_point_cache_keys()`
      - `CottonCandy.webpack_entry_point_directory_path()`
    - `CottonCandyConfiguration`
      - `CottonCandyConfiguration.DEFAULT_LINK_ACTIVE_COLOR`
      - `CottonCandyConfiguration.DEFAULT_LINK_INACTIVE_COLOR`
      - `CottonCandyConfiguration.DEFAULT_PRIMARY_ACTIVE_COLOR`
      - `CottonCandyConfiguration.DEFAULT_PRIMARY_INACTIVE_COLOR`
      - `CottonCandyConfiguration.__init__()`
      - `CottonCandyConfiguration.dump()`
      - `CottonCandyConfiguration.featured_entities`
      - `CottonCandyConfiguration.link_active_color`
      - `CottonCandyConfiguration.link_inactive_color`
      - `CottonCandyConfiguration.load()`
      - `CottonCandyConfiguration.logo`
      - `CottonCandyConfiguration.primary_active_color`
      - `CottonCandyConfiguration.primary_inactive_color`
    - `person_descendant_families()`
    - `person_timeline_events()`
- betty.extension.demo package
  - Module contents
    - `Demo`
      - `Demo.depends_on()`
      - `Demo.load()`
      - `Demo.name()`
      - `Demo.project()`
    - `DemoServer`
      - `DemoServer.__init__()`
      - `DemoServer.label()`
      - `DemoServer.public_url`
      - `DemoServer.start()`
      - `DemoServer.stop()`
- betty.extension.deriver package
  - Module contents
    - `Deriver`
      - `Deriver.comes_before()`
      - `Deriver.description()`
      - `Deriver.label()`
      - `Deriver.name()`
      - `Deriver.post_load()`
- betty.extension.gramps package
  - Submodules
    - betty.extension.gramps.config module
      - `FamilyTreeConfiguration`
        - `FamilyTreeConfiguration.__init__()`
        - `FamilyTreeConfiguration.dump()`
        - `FamilyTreeConfiguration.file_path`
        - `FamilyTreeConfiguration.load()`
        - `FamilyTreeConfiguration.update()`
      - `FamilyTreeConfigurationSequence`
      - `GrampsConfiguration`
        - `GrampsConfiguration.__init__()`
        - `GrampsConfiguration.dump()`
        - `GrampsConfiguration.family_trees`
        - `GrampsConfiguration.load()`
        - `GrampsConfiguration.update()`
    - betty.extension.gramps.gui module
  - Module contents
    - `Gramps`
      - `Gramps.default_configuration()`
      - `Gramps.description()`
      - `Gramps.gui_build()`
      - `Gramps.label()`
      - `Gramps.load()`
      - `Gramps.name()`
- betty.extension.http_api_doc package
  - Module contents
    - `HttpApiDoc`
      - `HttpApiDoc.assets_directory_path()`
      - `HttpApiDoc.depends_on()`
      - `HttpApiDoc.description()`
      - `HttpApiDoc.label()`
      - `HttpApiDoc.name()`
      - `HttpApiDoc.webpack_entry_point_cache_keys()`
      - `HttpApiDoc.webpack_entry_point_directory_path()`
- betty.extension.maps package
  - Module contents
    - `Maps`
      - `Maps.assets_directory_path()`
      - `Maps.depends_on()`
      - `Maps.description()`
      - `Maps.label()`
      - `Maps.name()`
      - `Maps.webpack_entry_point_cache_keys()`
      - `Maps.webpack_entry_point_directory_path()`
- betty.extension.nginx package
  - Submodules
    - betty.extension.nginx.artifact module
      - `generate_configuration_file()`
      - `generate_dockerfile_file()`
    - betty.extension.nginx.cli module
    - betty.extension.nginx.config module
      - `NginxConfiguration`
        - `NginxConfiguration.__init__()`
        - `NginxConfiguration.dump()`
        - `NginxConfiguration.https`
        - `NginxConfiguration.load()`
        - `NginxConfiguration.update()`
        - `NginxConfiguration.www_directory_path`
    - betty.extension.nginx.docker module
      - `Container`
        - `Container.__init__()`
        - `Container.ip`
        - `Container.start()`
        - `Container.stop()`
    - betty.extension.nginx.gui module
    - betty.extension.nginx.serve module
      - `DockerizedNginxServer`
        - `DockerizedNginxServer.__init__()`
        - `DockerizedNginxServer.is_available()`
        - `DockerizedNginxServer.public_url`
        - `DockerizedNginxServer.start()`
        - `DockerizedNginxServer.stop()`
  - Module contents
    - `Nginx`
      - `Nginx.assets_directory_path()`
      - `Nginx.commands`
      - `Nginx.default_configuration()`
      - `Nginx.description()`
      - `Nginx.generate()`
      - `Nginx.gui_build()`
      - `Nginx.https`
      - `Nginx.label()`
      - `Nginx.servers`
      - `Nginx.www_directory_path`
- betty.extension.privatizer package
  - Module contents
    - `Privatizer`
      - `Privatizer.description()`
      - `Privatizer.label()`
      - `Privatizer.name()`
      - `Privatizer.post_load()`
      - `Privatizer.privatize()`
- betty.extension.trees package
  - Module contents
    - `Trees`
      - `Trees.assets_directory_path()`
      - `Trees.depends_on()`
      - `Trees.description()`
      - `Trees.label()`
      - `Trees.name()`
      - `Trees.webpack_entry_point_cache_keys()`
      - `Trees.webpack_entry_point_directory_path()`
- betty.extension.webpack package
  - Subpackages
    - betty.extension.webpack.jinja2 package
      - Submodules
        - betty.extension.webpack.jinja2.filter module
          - `filter_webpack_entry_point_js()`
      - Module contents
  - Submodules
    - betty.extension.webpack.build module
      - `Builder`
        - `Builder.__init__()`
        - `Builder.build()`
      - `webpack_build_id()`
  - Module contents
    - `PrebuiltAssetsRequirement`
      - `PrebuiltAssetsRequirement.is_met()`
      - `PrebuiltAssetsRequirement.summary()`
    - `Webpack`
      - `Webpack.assets_directory_path()`
      - `Webpack.build_requirement()`
      - `Webpack.enable_requirement()`
      - `Webpack.filters`
      - `Webpack.generate()`
      - `Webpack.name()`
      - `Webpack.new_context_vars()`
      - `Webpack.prebuild()`
      - `Webpack.public_css_paths`
    - `WebpackEntryPointProvider`
      - `WebpackEntryPointProvider.webpack_entry_point_cache_keys()`
      - `WebpackEntryPointProvider.webpack_entry_point_directory_path()`
- betty.extension.wikipedia package
  - Submodules
    - betty.extension.wikipedia.config module
      - `WikipediaConfiguration`
        - `WikipediaConfiguration.__init__()`
        - `WikipediaConfiguration.dump()`
        - `WikipediaConfiguration.load()`
        - `WikipediaConfiguration.populate_images`
        - `WikipediaConfiguration.update()`
    - betty.extension.wikipedia.gui module
  - Module contents
    - `Wikipedia`
      - `Wikipedia.__init__()`
      - `Wikipedia.assets_directory_path()`
      - `Wikipedia.default_configuration()`
      - `Wikipedia.description()`
      - `Wikipedia.filters`
      - `Wikipedia.gui_build()`
      - `Wikipedia.label()`
      - `Wikipedia.name()`
      - `Wikipedia.post_load()`

## Module contents

Provide the built-in extensions.

class betty.extension.CottonCandy

  Bases: `Theme`, `CssProvider`, `ConfigurableExtension`[`CottonCandyConfiguration`], `Generator`, `GuiBuilder`, `Jinja2Provider`, `WebpackEntryPointProvider`

  Provide Betty’s default front-end theme.

  Parameters:

    - args (`typing.Any`)

    - configuration (`typing.Optional`[`typing.TypeVar`(`ConfigurationT`, bound= `betty.config.Configuration`)])

    - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path`

  classmethod comes_after() → set[type[betty.app.extension.Extension]]

    The extensions that this one comes after.

    The other extensions may or may not be enabled.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod default_configuration() → betty.extension.cotton_candy.CottonCandyConfiguration

    Get this extension’s default configuration.

    Return type:

      `betty.extension.cotton_candy.CottonCandyConfiguration`

  classmethod depends_on() → set[type[betty.app.extension.Extension]]

    The extensions this one depends on, and comes after.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  property filters: dict[str, Callable[[...], Any]]

    Jinja2 filters provided by this extension.

    Keys are filter names, and values are the filters themselves.

  async generate(job_context: betty.generate.GenerationContext) → None

    Generate (part of) a project’s site.

    Parameters:

      job_context (`betty.generate.GenerationContext`)

    Return type:

      `None`

  property globals: dict[str, Any]

    Jinja2 globals provided by this extension.

    Keys are the globals’ names, and values are the globals’ values.

  gui_build() → PyQt6.QtWidgets.QWidget

    Build this extension’s Graphical User Interface component.

    Return type:

      `PyQt6.QtWidgets.QWidget`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  property logo: Path

    The path to the logo file.

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  property public_css_paths: list[str]

    The public URL paths to the CSS files to include in each HTML page.

  webpack_entry_point_cache_keys() → collections.abc.Sequence[str]

    Get the keys that make a Webpack build for this provider unique.

    Providers that can be cached regardless may `return ()`.

    Return type:

      `collections.abc.Sequence`[`str`]

  classmethod webpack_entry_point_directory_path() → pathlib._local.Path

    Get the path to the directory with the entry point assets.

    The directory must include at least a `package.json` and `main.ts`.

    Return type:

      `pathlib._local.Path`

class betty.extension.Demo

  Bases: `Extension`, `Loader`

  Provide demonstration site functionality.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod depends_on() → set[type[betty.app.extension.Extension]]

    The extensions this one depends on, and comes after.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  async load() → None

    Load ancestry data.

    Return type:

      `None`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  classmethod project() → betty.project.Project

    Create a new demonstration project.

    Return type:

      `betty.project.Project`

class betty.extension.Deriver

  Bases: `UserFacingExtension`, `PostLoader`

  Expand an ancestry by deriving additional data from existing data.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod comes_before() → set[type[betty.app.extension.Extension]]

    The extensions that this one comes before.

    The other extensions may or may not be enabled.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  async post_load() → None

    Act on the ancestry having been loaded.

    This method is called immediately after `betty.load.Loader.load()`.

    Return type:

      `None`

class betty.extension.Gramps

  Bases: `ConfigurableExtension`[`GrampsConfiguration`], `UserFacingExtension`, `Loader`, `GuiBuilder`

  Integrate Betty with Gramps.

  Parameters:

    - args (`typing.Any`)

    - configuration (`typing.Optional`[`typing.TypeVar`(`ConfigurationT`, bound= `betty.config.Configuration`)])

    - kwargs (`typing.Any`)

  classmethod default_configuration() → betty.extension.gramps.config.GrampsConfiguration

    Get this extension’s default configuration.

    Return type:

      `betty.extension.gramps.config.GrampsConfiguration`

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  gui_build() → betty.extension.gramps.gui._GrampsGuiWidget

    Build this extension’s Graphical User Interface component.

    Return type:

      `betty.extension.gramps.gui._GrampsGuiWidget`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  async load() → None

    Load ancestry data.

    Return type:

      `None`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

class betty.extension.HttpApiDoc

  Bases: `UserFacingExtension`, `WebpackEntryPointProvider`

  Provide user-friendly HTTP API documentation.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path`

  classmethod depends_on() → set[type[betty.app.extension.Extension]]

    The extensions this one depends on, and comes after.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  webpack_entry_point_cache_keys() → collections.abc.Sequence[str]

    Get the keys that make a Webpack build for this provider unique.

    Providers that can be cached regardless may `return ()`.

    Return type:

      `collections.abc.Sequence`[`str`]

  classmethod webpack_entry_point_directory_path() → pathlib._local.Path

    Get the path to the directory with the entry point assets.

    The directory must include at least a `package.json` and `main.ts`.

    Return type:

      `pathlib._local.Path`

class betty.extension.Maps

  Bases: `UserFacingExtension`, `WebpackEntryPointProvider`

  Provide interactive maps for use on web pages.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path`

  classmethod depends_on() → set[type[betty.app.extension.Extension]]

    The extensions this one depends on, and comes after.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  webpack_entry_point_cache_keys() → collections.abc.Sequence[str]

    Get the keys that make a Webpack build for this provider unique.

    Providers that can be cached regardless may `return ()`.

    Return type:

      `collections.abc.Sequence`[`str`]

  classmethod webpack_entry_point_directory_path() → pathlib._local.Path

    Get the path to the directory with the entry point assets.

    The directory must include at least a `package.json` and `main.ts`.

    Return type:

      `pathlib._local.Path`

class betty.extension.Nginx

  Bases: `ConfigurableExtension`[`NginxConfiguration`], `UserFacingExtension`, `Generator`, `ServerProvider`, `GuiBuilder`, `CommandProvider`

  Integrate Betty with nginx (and Docker).

  Parameters:

    - args (`typing.Any`)

    - configuration (`typing.Optional`[`typing.TypeVar`(`ConfigurationT`, bound= `betty.config.Configuration`)])

    - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path | None

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path` | `None`

  property commands: dict[str, Command]

    The commands to provide.

  classmethod default_configuration() → betty.extension.nginx.config.NginxConfiguration

    Get this extension’s default configuration.

    Return type:

      `betty.extension.nginx.config.NginxConfiguration`

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  async generate(job_context: betty.generate.GenerationContext) → None

    Generate (part of) a project’s site.

    Parameters:

      job_context (`betty.generate.GenerationContext`)

    Return type:

      `None`

  gui_build() → betty.extension.nginx.gui._NginxGuiWidget

    Build this extension’s Graphical User Interface component.

    Return type:

      `betty.extension.nginx.gui._NginxGuiWidget`

  property https: bool

    Whether the nginx server should use HTTPS.

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  property servers: Sequence[Server]

    Provide one or more web servers.

  property www_directory_path: str

    The nginx server’s public web root directory path.

class betty.extension.Privatizer

  Bases: `UserFacingExtension`, `PostLoader`

  Extend the Betty Application with privatization features.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  async post_load() → None

    Act on the ancestry having been loaded.

    This method is called immediately after `betty.load.Loader.load()`.

    Return type:

      `None`

  privatize() → None

    Privatize the project’s ancestry.

    Return type:

      `None`

class betty.extension.Trees

  Bases: `UserFacingExtension`, `WebpackEntryPointProvider`

  Provide interactive family trees for use in web pages.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path`

  classmethod depends_on() → set[type[betty.app.extension.Extension]]

    The extensions this one depends on, and comes after.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  webpack_entry_point_cache_keys() → collections.abc.Sequence[str]

    Get the keys that make a Webpack build for this provider unique.

    Providers that can be cached regardless may `return ()`.

    Return type:

      `collections.abc.Sequence`[`str`]

  classmethod webpack_entry_point_directory_path() → pathlib._local.Path

    Get the path to the directory with the entry point assets.

    The directory must include at least a `package.json` and `main.ts`.

    Return type:

      `pathlib._local.Path`

class betty.extension.Webpack

  Bases: `Extension`, `CssProvider`, `Jinja2Provider`, `Generator`

  Integrate Betty with Webpack.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path`

  build_requirement() → betty.requirement.Requirement

    Get the requirement that must be satisfied for Webpack builds to be available.

    Return type:

      `betty.requirement.Requirement`

  classmethod enable_requirement() → betty.requirement.Requirement

    Define the requirement for this extension to be enabled.

    This defaults to the extension’s dependencies.

    Return type:

      `betty.requirement.Requirement`

  property filters: dict[str, Callable[[...], Any]]

    Jinja2 filters provided by this extension.

    Keys are filter names, and values are the filters themselves.

  async generate(job_context: betty.generate.GenerationContext) → None

    Generate (part of) a project’s site.

    Parameters:

      job_context (`betty.generate.GenerationContext`)

    Return type:

      `None`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  new_context_vars() → dict[str, Any]

    Create new variables for a new `jinja2.runtime.Context`.

    Keys are the variable names, and values are variable values.

    Return type:

      `dict`[`str`, `typing.Any`]

  async prebuild(job_context: betty.job.Context) → None

    Prebuild the Webpack assets.

    Parameters:

      job_context (`betty.job.Context`)

    Return type:

      `None`

  property public_css_paths: list[str]

    The public URL paths to the CSS files to include in each HTML page.

class betty.extension.Wikipedia

  Bases: `ConfigurableExtension`[`WikipediaConfiguration`], `UserFacingExtension`, `Jinja2Provider`, `PostLoader`, `GuiBuilder`

  Integrates Betty with Wikipedia.

  Parameters:

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  __init__(*args: Any, **kwargs: Any)
    Parameters:

      - args (`typing.Any`)

      - kwargs (`typing.Any`)

  classmethod assets_directory_path() → pathlib._local.Path | None

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib._local.Path` | `None`

  classmethod default_configuration() → betty.extension.wikipedia.config.WikipediaConfiguration

    Get this extension’s default configuration.

    Return type:

      `betty.extension.wikipedia.config.WikipediaConfiguration`

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  property filters: dict[str, Callable[[...], Any]]

    Jinja2 filters provided by this extension.

    Keys are filter names, and values are the filters themselves.

  gui_build() → betty.extension.wikipedia.gui._WikipediaGuiWidget

    Build this extension’s Graphical User Interface component.

    Return type:

      `betty.extension.wikipedia.gui._WikipediaGuiWidget`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

  async post_load() → None

    Act on the ancestry having been loaded.

    This method is called immediately after `betty.load.Loader.load()`.

    Return type:

      `None`