betty.project package¶
Subpackages¶
Submodules¶
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.
- __init__(entity_type: type[_EntityT] | None = None, entity_id: str | None = None, *, entity_type_is_constrained: bool = False)[source]¶
- 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] [source]¶
Dump this instance to a portable format.
- load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) None [source]¶
Load dumped configuration.
- Raises:
betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.
- 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.
- __init__(entity_references: Iterable[EntityReference[_EntityT]] | None = None, *, entity_type_constraint: type[_EntityT] | None = None)[source]¶
- load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) EntityReference[_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.
- final class betty.project.EntityTypeConfiguration[source]¶
Bases:
Configuration
Configure a single entity type for a project.
- 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] [source]¶
Dump this instance to a portable format.
- load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) None [source]¶
Load dumped configuration.
- Raises:
betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.
- final class betty.project.EntityTypeConfigurationMapping[source]¶
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 [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.
- final class betty.project.ExtensionConfiguration[source]¶
Bases:
Configuration
Configure a single extension for a project.
- __init__(extension_type: type[Extension], *, enabled: bool = True, extension_configuration: Configuration | None = None)[source]¶
- 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] [source]¶
Dump this instance to a portable format.
- property extension_configuration: Configuration | None¶
Get the extension’s own configuration.
- load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) None [source]¶
Load dumped configuration.
- Raises:
betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.
- final class betty.project.ExtensionConfigurationMapping[source]¶
Bases:
ConfigurationMapping
[type
[Extension
],ExtensionConfiguration
]Configure a project’s extensions.
- __init__(configurations: Iterable[ExtensionConfiguration] | None = None)[source]¶
- load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) 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.
- final class betty.project.LocaleConfiguration[source]¶
Bases:
Configuration
Configure a single project locale.
- 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] [source]¶
Dump this instance to a portable format.
- load(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) None [source]¶
Load dumped configuration.
- Raises:
betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.
- property locale: str¶
An IETF BCP 47 language tag.
- final class betty.project.LocaleConfigurationSequence[source]¶
Bases:
ConfigurationSequence
[LocaleConfiguration
]Configure a project’s locales.
- __init__(configurations: Iterable[LocaleConfiguration] | None = None)[source]¶
- property default: LocaleConfiguration¶
The default language.
- load_item(dump: bool | int | float | str | None | MutableSequence[Dump] | MutableMapping[str, Dump]) 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.
- replace(*configurations: LocaleConfiguration) None [source]¶
Replace any existing values with the given ones.
- final class betty.project.Project[source]¶
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)[source]¶
- property assets: AssetRepository¶
The assets file system.
- 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 [source]¶
Create a new instance of a type that depends on a
self
.
- classmethod new_temporary(app: App, *, ancestry: Ancestry | None = None) 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.
- 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
.- __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)[source]¶
- author¶
A property (similar to
property()
) that containsbetty.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 ishttps://example.com
. If the public URL ishttps://example.com/my-ancestry-site
, the base URL ishttps://example.com
. If the public URL ishttps://my-ancestry-site.example.com
, the base URL ishttps://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 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]]] [source]¶
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 [source]¶
Load dumped configuration.
- Raises:
betty.assertion.error.AssertionFailed – Raised if the dump contains invalid configuration.
- property locales: LocaleConfigurationSequence¶
The available locales.
- 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 ishttps://example.com/my-ancestry-site
, the root path is/my-ancestry-site
.
- title¶
A property (similar to
property()
) that containsbetty.locale.localizable.StaticTranslationsLocalizableConfiguration
.
- class betty.project.ProjectEvent[source]¶
Bases:
Event
An event that is dispatched within the context of a
betty.project.Project
.- property project: Project¶
The
betty.project.Project
this event is dispatched within.