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

# betty.project package

## Subpackages

- betty.project.extension package
  - Submodules
    - betty.project.extension.requirement module
      - `Dependencies`
        - `Dependencies.__init__()`
        - `Dependencies.summary()`
      - `Dependents`
        - `Dependents.__init__()`
        - `Dependents.is_met()`
        - `Dependents.summary()`
  - Module contents
    - `ConfigurableExtension`
      - `ConfigurableExtension.__init__()`
      - `ConfigurableExtension.default_configuration()`
    - `CyclicDependencyError`
      - `CyclicDependencyError.__init__()`
    - `EXTENSION_REPOSITORY`
    - `Extension`
      - `Extension.__init__()`
      - `Extension.assets_directory_path()`
      - `Extension.comes_after()`
      - `Extension.comes_before()`
      - `Extension.depends_on()`
      - `Extension.disable_requirement()`
      - `Extension.enable_requirement()`
      - `Extension.new_for_project()`
      - `Extension.project`
      - `Extension.register_event_handlers()`
    - `ExtensionError`
    - `Theme`
    - `build_extension_type_graph()`

## Submodules

- betty.project.factory module
  - `ProjectDependentFactory`
    - `ProjectDependentFactory.new_for_project()`

## Module contents

Provide the project API.

Projects are how people use Betty. A project is a workspace, starting out with the user’s configuration, and combining it with the resulting ancestry, allowing the user to perform tasks, such as generating a site from the entire project.

betty.project.DEFAULT_LIFETIME_THRESHOLD = 125

  The default age by which people are presumed dead.

final class betty.project.EntityReference

  Bases: `Configuration`, `Generic`[`_EntityT`]

  Configuration that references an entity from the project’s ancestry.

  __init__(entity_type: type[_EntityT] | None = None, entity_id: str | None = None, *, entity_type_is_constrained: bool = False)
  dump() → bool | int | float | str | None | MutableSequence[bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | MutableMapping[str, bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | type[Void]

    Dump this instance to a portable format.

  property entity_id: str | None

    The referenced entity’s ID.

  property entity_type: type[_EntityT] | None

    The referenced entity’s type.

  property entity_type_is_constrained: bool

    Whether the entity type may be changed.

  load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → None

    Load dumped configuration.

    Raises:

      betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.

  update(other: Self) → None

    Update this configuration with the values from `other`.

final class betty.project.EntityReferenceSequence

  Bases: `Generic`[`_EntityT`], `ConfigurationSequence`[`EntityReference`[`_EntityT`]]

  Configuration for a sequence of references to entities from the project’s ancestry.

  __init__(entity_references: Iterable[EntityReference[_EntityT]] | None = None, *, entity_type_constraint: type[_EntityT] | None = None)
  load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → EntityReference[_EntityT]

    Create and load a new item from the given dump, or raise an assertion error.

    Raises:

      betty.assertion.error.AssertionFailed – Raised when the dump is invalid and cannot be loaded.

final class betty.project.EntityTypeConfiguration

  Bases: `Configuration`

  Configure a single entity type for a project.

  __init__(entity_type: type[Entity], *, generate_html_list: bool | None = None)
  dump() → bool | int | float | str | None | MutableSequence[bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | MutableMapping[str, bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | type[Void]

    Dump this instance to a portable format.

  property entity_type: type[Entity]

    The configured entity type.

  property generate_html_list: bool

    Whether to generate listing web pages for entities of this type.

  load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → None

    Load dumped configuration.

    Raises:

      betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.

  update(other: Self) → None

    Update this configuration with the values from `other`.

final class betty.project.EntityTypeConfigurationMapping

  Bases: `ConfigurationMapping`[`type`[`Entity`], `EntityTypeConfiguration`]

  Configure the entity types for a project.

  load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → EntityTypeConfiguration

    Create and load a new item from the given dump, or raise an assertion error.

    Raises:

      betty.assertion.error.AssertionFailed – Raised when the dump is invalid and cannot be loaded.

final class betty.project.ExtensionConfiguration

  Bases: `Configuration`

  Configure a single extension for a project.

  __init__(extension_type: type[Extension], *, enabled: bool = True, extension_configuration: Configuration | None = None)
  dump() → bool | int | float | str | None | MutableSequence[bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | MutableMapping[str, bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | type[Void]

    Dump this instance to a portable format.

  property enabled: bool

    Whether the extension is enabled.

  property extension_configuration: Configuration | None

    Get the extension’s own configuration.

  property extension_type: type[Extension]

    The extension type.

  load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → None

    Load dumped configuration.

    Raises:

      betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.

  update(other: Self) → None

    Update this configuration with the values from `other`.

final class betty.project.ExtensionConfigurationMapping

  Bases: `ConfigurationMapping`[`type`[`Extension`], `ExtensionConfiguration`]

  Configure a project’s extensions.

  __init__(configurations: Iterable[ExtensionConfiguration] | None = None)
  disable(*extension_types: type[Extension]) → None

    Disable the given extensions.

  enable(*extension_types: type[Extension]) → None

    Enable the given extensions.

  load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → ExtensionConfiguration

    Create and load a new item from the given dump, or raise an assertion error.

    Raises:

      betty.assertion.error.AssertionFailed – Raised when the dump is invalid and cannot be loaded.

final class betty.project.LocaleConfiguration

  Bases: `Configuration`

  Configure a single project locale.

  __init__(locale: str, *, alias: str | None = None)
  property alias: str

    A shorthand alias to use instead of the full language tag, such as when rendering URLs.

  dump() → bool | int | float | str | None | MutableSequence[bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | MutableMapping[str, bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | type[Void]

    Dump this instance to a portable format.

  load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → None

    Load dumped configuration.

    Raises:

      betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.

  property locale: str

    An IETF BCP 47 language tag.

  update(other: Self) → None

    Update this configuration with the values from `other`.

final class betty.project.LocaleConfigurationSequence

  Bases: `ConfigurationSequence`[`LocaleConfiguration`]

  Configure a project’s locales.

  __init__(configurations: Iterable[LocaleConfiguration] | None = None)
  property default: LocaleConfiguration

    The default language.

  load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → LocaleConfiguration

    Create and load a new item from the given dump, or raise an assertion error.

    Raises:

      betty.assertion.error.AssertionFailed – Raised when the dump is invalid and cannot be loaded.

  property multilingual: bool

    Whether the configuration is multilingual.

  replace(*configurations: LocaleConfiguration) → None

    Replace any existing values with the given ones.

  update(other: Self) → None

    Update this configuration with the values from `other`.

final class betty.project.Project

  Bases: `Configurable`[`ProjectConfiguration`], `CoreComponent`

  Define a Betty project.

  A project combines project configuration and the resulting ancestry.

  __init__(app: App, configuration: ProjectConfiguration, *, ancestry: Ancestry | None = None)
  property ancestry: Ancestry

    The project’s ancestry.

  property app: App

    The application this project is run within.

  property assets: AssetRepository

    The assets file system.

  async bootstrap() → None

    Bootstrap the component.

  property event_dispatcher: EventDispatcher

    The event dispatcher.

  property extensions: _ProjectExtensions

    The enabled extensions.

  property jinja2_environment: Environment

    The Jinja2 environment.

  property localizers: LocalizerRepository

    The available localizers.

  property name: str

    The project name.

    If no project name was configured, this defaults to the hash of the configuration file path.

  new_dependent(dependent: type[_ProjectDependentFactoryT]) → _ProjectDependentFactoryT

    Create a new instance of a type that depends on a `self`.

  classmethod new_temporary(app: App, *, ancestry: Ancestry | None = None) → AsyncIterator[Self]

    Creat a new, temporary, isolated project.

    The project will not leave any traces on the system, except when it uses global Betty functionality such as caches.

  property renderer: Renderer

    The (file) content renderer.

  property static_url_generator: StaticUrlGenerator

    The static URL generator.

  property url_generator: LocalizedUrlGenerator

    The (localized) URL generator.

final class betty.project.ProjectConfiguration

  Bases: `Configuration`

  Provide the configuration for a `betty.project.Project`.

  __init__(configuration_file_path: Path, *, url: str = 'https://example.com', clean_urls: bool = False, title: Mapping[str, str] | str = 'Betty', author: Mapping[str, str] | str | None = None, entity_types: Iterable[EntityTypeConfiguration] | None = None, extensions: Iterable[ExtensionConfiguration] | None = None, debug: bool = False, locales: Iterable[LocaleConfiguration] | None = None, lifetime_threshold: int = 125, name: str | None = None)
  property assets_directory_path: Path

    The assets directory path.

  author

    A property (similar to `property()`) that contains `betty.locale.localizable.StaticTranslationsLocalizableConfiguration`.

  property base_url: str

    The project’s public URL’s base URL.

    If the public URL is `https://example.com`, the base URL is `https://example.com`. If the public URL is `https://example.com/my-ancestry-site`, the base URL is `https://example.com`. If the public URL is `https://my-ancestry-site.example.com`, the base URL is `https://my-ancestry-site.example.com`.

  property clean_urls: bool

    Whether to generate clean URLs such as `/person/first-person` instead of `/person/first-person/index.html`.

    Generated artifacts will require web server that supports this.

  property configuration_file_path: Path

    The path to the configuration’s file.

  property debug: bool

    Whether to enable debugging for project jobs.

    This setting is disabled by default.

    Enabling this generally results in:

    - More verbose logging output

    - job artifacts (e.g. generated sites)

  dump() → MutableMapping[str, bool | int | float | str | None | MutableSequence[bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]] | MutableMapping[str, bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]]]

    Dump this instance to a portable format.

  property entity_types: EntityTypeConfigurationMapping

    The available entity types.

  property extensions: ExtensionConfigurationMapping

    Then extensions running within this application.

  property lifetime_threshold: int

    The lifetime threshold indicates when people are considered dead.

    This setting defaults to `betty.project.DEFAULT_LIFETIME_THRESHOLD`.

    The value is an integer expressing the age in years over which people are presumed to have died.

  load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) → None

    Load dumped configuration.

    Raises:

      betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.

  property locales: LocaleConfigurationSequence

    The available locales.

  localize_www_directory_path(locale: str) → Path

    Get the WWW directory path for a locale.

  property name: str | None

    The project’s machine name.

  property output_directory_path: Path

    The output directory path.

  property project_directory_path: Path

    The project directory path.

    Betty will look for resources in this directory, and place generated artifacts there. It is expected that no other applications or projects share this same directory.

  property root_path: str

    The project’s public URL’s root path.

    If the public URL is `https://example.com`, the root path is an empty string. If the public URL is `https://example.com/my-ancestry-site`, the root path is `/my-ancestry-site`.

  title

    A property (similar to `property()`) that contains `betty.locale.localizable.StaticTranslationsLocalizableConfiguration`.

  update(other: Self) → None

    Update this configuration with the values from `other`.

  property url: str

    The project’s public URL.

  property www_directory_path: Path

    The WWW directory path.

class betty.project.ProjectEvent

  Bases: `Event`

  An event that is dispatched within the context of a `betty.project.Project`.

  __init__(project: Project)
  property project: Project

    The `betty.project.Project` this event is dispatched within.