betty.project module¶
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.serde.dump.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.serde.dump.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.serde.load.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.serde.dump.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.serde.dump.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.serde.load.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.app.extension.Extension
])enabled (
bool
)extension_configuration (
betty.config.Configuration
|None
)
- __init__(extension_type: type[betty.app.extension.Extension], *, enabled: bool = True, extension_configuration: betty.config.Configuration | None = None)[source]¶
- Parameters:
extension_type (
type
[betty.app.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.serde.dump.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.serde.dump.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.app.extension.Extension]) None [source]¶
Disable the given extensions.
- Parameters:
extension_types (
type
[betty.app.extension.Extension
])- Return type:
- enable(*extension_types: type[betty.app.extension.Extension]) None [source]¶
Enable the given extensions.
- Parameters:
extension_types (
type
[betty.app.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.serde.load.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.serde.dump.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.serde.dump.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.serde.load.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
]Define a Betty project.
A project combines project configuration and the resulting ancestry.
- Parameters:
ancestry (
betty.model.ancestry.Ancestry
|None
)
- __init__(*, ancestry: betty.model.ancestry.Ancestry | None = None)[source]¶
- Parameters:
ancestry (
betty.model.ancestry.Ancestry
|None
)
- final class betty.project.ProjectConfiguration[source]¶
Bases:
FileBasedConfiguration
Provide the configuration for a
betty.project.Project
.- Parameters:
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__(*, 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:
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
.