betty.project package¶
Submodules¶
- betty.project.extension module
ConfigurableExtension
CyclicDependencyError
Dependencies
Dependents
Extension
ExtensionDispatcher
ExtensionError
ExtensionTypeError
ExtensionTypeImportError
ExtensionTypeInvalidError
Extensions
ListExtensions
Theme
UserFacingExtension
build_extension_type_graph()
discover_extension_types()
format_extension_type()
get_extension_type()
get_extension_type_by_extension()
get_extension_type_by_name()
get_extension_type_by_type()
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.
- class betty.project.EntityReference[source]¶
Bases:
Configuration
,Generic
[_EntityT
]Configuration that references an entity from the project’s ancestry.
- Parameters:
entity_type (
type
[typing.TypeVar
(_EntityT
, bound=betty.model.Entity
)] |None
)entity_type_is_constrained (
bool
)
- __init__(entity_type: type[betty.project._EntityT] | None = None, entity_id: str | None = None, *, entity_type_is_constrained: bool = False)[source]¶
- Parameters:
entity_type (
type
[typing.TypeVar
(_EntityT
, bound=betty.model.Entity
)] |None
)entity_type_is_constrained (
bool
)
- 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
]]
- 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:
entity_references (
typing.Optional
[typing.Iterable
[betty.project.EntityReference
[typing.TypeVar
(_EntityT
, bound=betty.model.Entity
)]]])entity_type_constraint (
type
[typing.TypeVar
(_EntityT
, bound=betty.model.Entity
)] |None
)
- __init__(entity_references: Iterable[betty.project.EntityReference[betty.project._EntityT]] | None = None, *, entity_type_constraint: type[betty.project._EntityT] | None = None)[source]¶
- Parameters:
entity_references (
typing.Optional
[typing.Iterable
[betty.project.EntityReference
[typing.TypeVar
(_EntityT
, bound=betty.model.Entity
)]]])entity_type_constraint (
type
[typing.TypeVar
(_EntityT
, bound=betty.model.Entity
)] |None
)
- 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
)]
- class betty.project.EntityTypeConfiguration[source]¶
Bases:
Configuration
Configure a single entity type for a project.
- Parameters:
entity_type (
type
[betty.model.Entity
])
- __init__(entity_type: type[betty.model.Entity], *, generate_html_list: bool | None = None)[source]¶
- Parameters:
entity_type (
type
[betty.model.Entity
])
- 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
]]
- 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:
- class betty.project.ExtensionConfiguration[source]¶
Bases:
Configuration
Configure a single extension for a project.
- Parameters:
extension_type (
type
[betty.project.extension.Extension
])enabled (
bool
)extension_configuration (
betty.config.Configuration
|None
)
- __init__(extension_type: type[betty.project.extension.Extension], *, enabled: bool = True, extension_configuration: betty.config.Configuration | None = None)[source]¶
- Parameters:
extension_type (
type
[betty.project.extension.Extension
])enabled (
bool
)extension_configuration (
betty.config.Configuration
|None
)
- classmethod assert_load() Callable[[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]]], betty.project.ExtensionConfiguration] [source]¶
Build an assertion to create a new instance and load a configuration dump into it.
- Return type:
typing.Callable
[[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]]]]],betty.project.ExtensionConfiguration
]
- 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 extension_configuration: Configuration | None¶
Get the extension’s own configuration.
- 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:
- enable(*extension_types: type[betty.project.extension.Extension]) None [source]¶
Enable the given extensions.
- Parameters:
extension_types (
type
[betty.project.extension.Extension
])- Return type:
- 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:
- 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 | 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.
- Parameters:
dump (
typing.Union
[bool
,int
,float
,str
,None
,typing.Sequence
[Dump],typing.Mapping
[str
, Dump]])- Return type:
- property locale: str¶
An IETF BCP 47 language tag.
- 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:
- class betty.project.Project[source]¶
Bases:
Configurable
[ProjectConfiguration
],CoreComponent
Define a Betty project.
A project combines project configuration and the resulting ancestry.
- Parameters:
app (
betty.app.App
)configuration (
betty.project.ProjectConfiguration
)ancestry (
betty.model.ancestry.Ancestry
|None
)
- __init__(app: betty.app.App, configuration: betty.project.ProjectConfiguration, *, ancestry: betty.model.ancestry.Ancestry | None = None)[source]¶
- Parameters:
app (
betty.app.App
)configuration (
betty.project.ProjectConfiguration
)ancestry (
betty.model.ancestry.Ancestry
|None
)
- property assets: AssetRepository¶
The assets file system.
- discover_extension_types() set[type[betty.project.extension.Extension]] [source]¶
Discover the available extension types.
- Return type:
- 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:
app (
betty.app.App
)ancestry (
betty.model.ancestry.Ancestry
|None
)
- Return type:
collections.abc.AsyncIterator
[typing.Self
]
- property static_url_generator: StaticUrlGenerator¶
The static URL generator.
- property url_generator: LocalizedUrlGenerator¶
The (localized) URL generator.
- final class betty.project.ProjectConfiguration[source]¶
Bases:
FileBasedConfiguration
Provide the configuration for a
betty.project.Project
.- Parameters:
configuration_file_path (
pathlib.Path
)root_path (
str
)clean_urls (
bool
)title (
str
)entity_types (
typing.Optional
[typing.Iterable
[betty.project.EntityTypeConfiguration
]])extensions (
typing.Optional
[typing.Iterable
[betty.project.ExtensionConfiguration
]])debug (
bool
)locales (
typing.Optional
[typing.Iterable
[betty.project.LocaleConfiguration
]])lifetime_threshold (
int
)
- __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:
configuration_file_path (
pathlib.Path
)root_path (
str
)clean_urls (
bool
)title (
str
)entity_types (
typing.Optional
[typing.Iterable
[betty.project.EntityTypeConfiguration
]])extensions (
typing.Optional
[typing.Iterable
[betty.project.ExtensionConfiguration
]])debug (
bool
)locales (
typing.Optional
[typing.Iterable
[betty.project.LocaleConfiguration
]])lifetime_threshold (
int
)
- 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() 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.
- Parameters:
dump (
typing.Union
[bool
,int
,float
,str
,None
,typing.Sequence
[Dump],typing.Mapping
[str
, Dump]])- Return type:
- 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:
- 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
.