betty.project package

Subpackages

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[source]

Bases: Configuration, Generic[_EntityT]

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

Parameters:
__init__(entity_type: type[betty.project._EntityT] | None = None, entity_id: str | None = None, *, entity_type_is_constrained: bool = False)[source]
Parameters:
dump() bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | type[betty.typing.Void][source]

Dump this instance to a portable format.

Return type:

typing.Union[bool, int, float, str, None, typing.Sequence[typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], typing.Mapping[str, typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], type[betty.typing.Void]]

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 | Sequence[Dump] | Mapping[str, Dump]) None[source]

Load dumped configuration.

Raises:

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

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

None

update(other: Self) None[source]

Update this configuration with the values from other.

Parameters:

other (typing.Self)

Return type:

None

final class betty.project.EntityReferenceSequence[source]

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

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

Parameters:
__init__(entity_references: Iterable[betty.project.EntityReference[betty.project._EntityT]] | None = None, *, entity_type_constraint: type[betty.project._EntityT] | None = None)[source]
Parameters:
load_item(dump: bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]) betty.project.EntityReference[betty.project._EntityT][source]

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.

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

betty.project.EntityReference[typing.TypeVar(_EntityT, bound= betty.model.Entity)]

final class betty.project.EntityTypeConfiguration[source]

Bases: Configuration

Configure a single entity type for a project.

Parameters:
__init__(entity_type: type[betty.model.Entity], *, generate_html_list: bool | None = None)[source]
Parameters:
dump() bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | type[betty.typing.Void][source]

Dump this instance to a portable format.

Return type:

typing.Union[bool, int, float, str, None, typing.Sequence[typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], typing.Mapping[str, typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], type[betty.typing.Void]]

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 | Sequence[Dump] | Mapping[str, Dump]) None[source]

Load dumped configuration.

Raises:

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

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

None

update(other: Self) None[source]

Update this configuration with the values from other.

Parameters:

other (typing.Self)

Return type:

None

final class betty.project.EntityTypeConfigurationMapping[source]

Bases: ConfigurationMapping[type[Entity], EntityTypeConfiguration]

Configure the entity types for a project.

Parameters:

configurations (typing.Optional[typing.Iterable[typing.TypeVar(_ConfigurationT, bound= betty.config.Configuration)]])

load_item(dump: bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]) betty.project.EntityTypeConfiguration[source]

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.

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

betty.project.EntityTypeConfiguration

final class betty.project.ExtensionConfiguration[source]

Bases: Configuration

Configure a single extension for a project.

Parameters:
__init__(extension_type: type[betty.project.extension.Extension], *, enabled: bool = True, extension_configuration: betty.config.Configuration | None = None)[source]
Parameters:
dump() bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | type[betty.typing.Void][source]

Dump this instance to a portable format.

Return type:

typing.Union[bool, int, float, str, None, typing.Sequence[typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], typing.Mapping[str, typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], type[betty.typing.Void]]

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 | Sequence[Dump] | Mapping[str, Dump]) None[source]

Load dumped configuration.

Raises:

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

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

None

update(other: Self) None[source]

Update this configuration with the values from other.

Parameters:

other (typing.Self)

Return type:

None

final class betty.project.ExtensionConfigurationMapping[source]

Bases: ConfigurationMapping[type[Extension], ExtensionConfiguration]

Configure a project’s extensions.

Parameters:

configurations (typing.Optional[typing.Iterable[betty.project.ExtensionConfiguration]])

__init__(configurations: Iterable[betty.project.ExtensionConfiguration] | None = None)[source]
Parameters:

configurations (typing.Optional[typing.Iterable[betty.project.ExtensionConfiguration]])

disable(*extension_types: type[betty.project.extension.Extension]) None[source]

Disable the given extensions.

Parameters:

extension_types (type[betty.project.extension.Extension])

Return type:

None

enable(*extension_types: type[betty.project.extension.Extension]) None[source]

Enable the given extensions.

Parameters:

extension_types (type[betty.project.extension.Extension])

Return type:

None

load_item(dump: bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]) betty.project.ExtensionConfiguration[source]

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.

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

betty.project.ExtensionConfiguration

final class betty.project.LocaleConfiguration[source]

Bases: Configuration

Configure a single project locale.

Parameters:
__init__(locale: str, *, alias: str | None = None)[source]
Parameters:
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 | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | type[betty.typing.Void][source]

Dump this instance to a portable format.

Return type:

typing.Union[bool, int, float, str, None, typing.Sequence[typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], typing.Mapping[str, typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], type[betty.typing.Void]]

load(dump: bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]) None[source]

Load dumped configuration.

Raises:

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

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

None

property locale: str

An IETF BCP 47 language tag.

update(other: Self) None[source]

Update this configuration with the values from other.

Parameters:

other (typing.Self)

Return type:

None

final class betty.project.LocaleConfigurationMapping[source]

Bases: ConfigurationMapping[str, LocaleConfiguration]

Configure a project’s locales.

Parameters:

configurations (typing.Optional[typing.Iterable[betty.project.LocaleConfiguration]])

__init__(configurations: Iterable[betty.project.LocaleConfiguration] | None = None)[source]
Parameters:

configurations (typing.Optional[typing.Iterable[betty.project.LocaleConfiguration]])

property default: LocaleConfiguration

The default language.

load_item(dump: bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]) betty.project.LocaleConfiguration[source]

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.

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

betty.project.LocaleConfiguration

property multilingual: bool

Whether the configuration is multilingual.

final class betty.project.Project[source]

Bases: Configurable[ProjectConfiguration], CoreComponent

Define a Betty project.

A project combines project configuration and the resulting ancestry.

Parameters:
__init__(app: betty.app.App, configuration: betty.project.ProjectConfiguration, *, ancestry: betty.model.ancestry.Ancestry | None = None)[source]
Parameters:
property ancestry: Ancestry

The project’s ancestry.

property app: App

The application this project is run within.

property assets: AssetRepository

The assets file system.

property dispatcher: Dispatcher

The event dispatcher.

property extensions: Extensions

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.

classmethod new_temporary(cls, app: betty.app.App, *, ancestry: betty.model.ancestry.Ancestry | None = None) collections.abc.AsyncIterator[Self][source]

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.

Parameters:
Return type:

collections.abc.AsyncIterator[typing.Self]

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[source]

Bases: Configuration

Provide the configuration for a betty.project.Project.

Parameters:
__init__(configuration_file_path: pathlib.Path, *, base_url: str | None = None, root_path: str = '', clean_urls: bool = False, title: str = 'Betty', author: str | None = None, entity_types: Iterable[betty.project.EntityTypeConfiguration] | None = None, extensions: Iterable[betty.project.ExtensionConfiguration] | None = None, debug: bool = False, locales: Iterable[betty.project.LocaleConfiguration] | None = None, lifetime_threshold: int = 125, name: str | None = None)[source]
Parameters:
property assets_directory_path: Path

The assets directory path.

property author: str | None

The project’s author.

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() dict[str, bool | int | float | str | None | Sequence[bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]] | Mapping[str, bool | int | float | str | None | Sequence[Dump] | Mapping[str, Dump]]][source]

Dump this instance to a portable format.

Return type:

dict[str, typing.Union[bool, int, float, str, None, typing.Sequence[typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]], typing.Mapping[str, typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]]]]]

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 | Sequence[Dump] | Mapping[str, Dump]) None[source]

Load dumped configuration.

Raises:

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

Parameters:

dump (typing.Union[bool, int, float, str, None, typing.Sequence[Dump], typing.Mapping[str, Dump]])

Return type:

None

property locales: LocaleConfigurationMapping

The available locales.

localize_www_directory_path(locale: str) pathlib.Path[source]

Get the WWW directory path for a locale.

Parameters:

locale (str)

Return type:

pathlib.Path

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.

property title: str

The project’s human-readable title.

update(other: Self) None[source]

Update this configuration with the values from other.

Parameters:

other (typing.Self)

Return type:

None

property www_directory_path: Path

The WWW directory path.