betty.project package¶

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.

final class betty.project.Project¶

Bases: DownstreamServiceLevel[App], RequirableServiceLevel, PluginServiceProvider

Define a Betty project.

A project combines project configuration and the resulting ancestry.

Configuration

betty.project.ProjectData

__init__(directory: StrPath, *, app: App, title: ResolvableLocalizable, url: str, ancestry: EntityPool | None = None, assets: Iterable[ResolvablePluginDefinition[AssetDirectoryDefinition]] = (), author: ResolvableLocalizable | None = None, cache: TypedSynchronousServiceOrFactory[Project, TransientStore[Any]] | None = None, clean_urls: bool = False, copyright_notice: ServicePluginInstance[CopyrightNoticeDefinition] | None = None, debug: bool = False, enrichers: ServicePluginInstances[EnricherDefinition] = (), extensions: ServicePluginInstances[ExtensionDefinition] = (), generate_entity_list_html: Iterable[ResolvablePluginId[EntityDefinition]] | None = None, license: ServicePluginInstance[LicenseDefinition] | None = None, lifetime_threshold: int | None = None, links: Iterable[ResolvablePluginDefinition[LinkDefinition]] = (), loaders: ServicePluginInstances[LoaderDefinition] = (), locales: Iterable[ProjectLocale | ResolvableLocale] = (), logo: StrPath | None = None, name: ResolvableMachineName | None = None, plugins: Mapping[type[PluginDefinition], Iterable[ResolvableDiscovery[PluginDefinition]]] | None = None, servers: ServicePluginInstances[ServerDefinition] = (), supported_plugins: SupportedPlugins = (), _plugin_discoveries: Iterable[PluginDefinition] = ())¶

ancestry: Final[EntityPool]¶: The project’s ancestry.

asset_directories¶: A service of plugin definitions keyed by their IDs.

asset_directory: Final[Path]¶: The asset directory path.

author: Final[Localizable | None]¶: The project’s author.

base_url: Final[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.

binary_file_cache¶: The project binary file cache.

cache¶: The project cache.

clean_urls: Final[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.

copyright_notice¶: A single plugin service.

css_resources¶: A service of plugin definitions keyed by their IDs.

debug: Final[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)

default_locale: Final[ProjectLocale]¶: The default locale.

directory: Final[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.

document_providers¶: A service of plugins keyed by their IDs.

enrichers¶: A service of plugins keyed by their IDs.

extensions¶: A service of plugins keyed by their IDs.

generate_entity_list_html¶: Which entity types to generate list HTML pages for.

jinja¶: The Jinja2 environment.

jinja_filters¶: A service of plugins keyed by their IDs.

jinja_tests¶: A service of plugins keyed by their IDs.

js_resources¶: A service of plugin definitions keyed by their IDs.

license¶: A single plugin service.

lifetime_threshold: Final[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.

links¶: A service of plugin definitions keyed by their IDs.

loaders¶: A service of plugins keyed by their IDs.

locales: KeyedCollection[Locale, ResolvableLocale, ProjectLocale]¶: The project locales.

localize_www_directory(locale: Locale) → Path¶: Get the WWW directory path for a locale.

localizers¶: The available localizers.

logo: Final[Path]¶: The path to the logo file.

multilingual: Final[bool]¶: Whether the project is multilingual.

name: Final[MachineName]¶

The project name.

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

async classmethod new(app: App, data: ProjectData, *, directory: StrPath) → Self¶: Create a new instance.

async new_document(resource: object = None, resource_url: object = None, /, *, media_type: ResolvableMediaType | None = None, **document_vars: Any) → Document¶: Create a new document.

classmethod new_isolated(*, ancestry: EntityPool | None = None, app: App | None = None, assets: Iterable[ResolvablePluginDefinition[AssetDirectoryDefinition]] = (), author: ResolvableLocalizable | None = None, cache: TypedSynchronousServiceOrFactory[Project, TransientStore[Any]] | None | Literal[False] = False, clean_urls: bool = False, debug: bool = False, directory: StrPath | None = None, enrichers: ServicePluginInstances[EnricherDefinition] = (), generate_entity_list_html: Iterable[ResolvablePluginId[EntityDefinition]] | None = None, extensions: ServicePluginInstances[ExtensionDefinition] = (), lifetime_threshold: int | None = None, links: Iterable[ResolvablePluginDefinition[LinkDefinition]] = (), loaders: ServicePluginInstances[LoaderDefinition] = (), locales: Iterable[ProjectLocale | ResolvableLocale] = (), logo: StrPath | None = None, name: ResolvableMachineName | None = None, plugins: Mapping[type[PluginDefinition], Iterable[ResolvableDiscovery[PluginDefinition]]] | None = None, servers: ServicePluginInstances[ServerDefinition] = (), supported_plugins: SupportedPlugins = (), title: ResolvableLocalizable | None = None, url: str | None = None) → AsyncIterator[Self]¶

Creat a new, isolated, temporary project.

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

output_directory: Final[Path]¶: The output directory path.

privatizer¶: The privatizer.

public_localizers¶: The public localizers.

renderer¶: The content renderer.

renderers¶: A service of plugins keyed by their IDs.

root_path: Final[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.

servers¶: A service of plugins keyed by their IDs.

title: Final[Localizable]¶: The human-readable project title.

translations¶: The available translations.

url: Final[str]¶: The project’s public URL.

url_generator¶: The URL generator.

www_directory: Final[Path]¶: The WWW directory path.

final class betty.project.ProjectData¶

Bases: Data, HasProps

Configuration for a betty.project.Project.

betty.project:ProjectData

__init__(*, title: ResolvableLocalizable, url: str, author: ResolvableLocalizable | None = None, clean_urls: bool = False, copyright_notice: ResolvablePluginManufacturer[CopyrightNoticeDefinition, CopyrightNotice] | None = None, copyright_notices: Iterable[CopyrightNoticeDefinitionData] = (), debug: bool = False, enrichers: ResolvablePluginManufacturerSequence[EnricherDefinition, Enricher] = (), event_types: Iterable[EventTypeDefinitionData] = (), extensions: ResolvablePluginManufacturerSequence[ExtensionDefinition, Extension] = (), generate_entity_list_html: Iterable[ResolvablePluginId[EntityDefinition]] | None = None, genders: Iterable[GenderDefinitionData] = (), license: ResolvablePluginManufacturer[LicenseDefinition, License] | None = None, licenses: Iterable[LicenseDefinitionData] = (), lifetime_threshold: int = 123, loaders: ResolvablePluginManufacturerSequence[LoaderDefinition, Loader] = (), locales: Iterable[ResolvableLocale | ProjectLocale] = (), logo: StrPath | None = None, name: ResolvableMachineName | None = None, place_types: Iterable[PlaceTypeDefinitionData] = (), roles: Iterable[RoleDefinitionData] = ())¶

author¶: The project’s author.

clean_urls¶: Whether to generate clean URLs.

copyright_notice¶: The project-wide copyright notice.

copyright_notices¶: The betty.copyright_notice.CopyrightNotice plugins created by this project.

debug¶: Whether to enable debugging for project jobs.

enrichers¶: The enrichers to enable for the project.

event_types¶: The betty.event_type.EventType plugins created by this project.

extensions¶: The extensions to enable for the project.

genders¶: The betty.gender.Gender plugins created by this project.

generate_entity_list_html¶: Which entity types to generate list HTML pages for.

license¶: The project-wide license.

licenses¶: The betty.license.License plugins created by this project.

lifetime_threshold¶: The lifetime threshold indicates when people are considered dead.

loaders¶: The loaders to enable for the project.

locales¶: The configured locales.

logo¶: The project logo.

name¶: The project’s machine name.

place_types¶: The betty.place_type.PlaceType plugins created by this project.

roles¶: The betty.role.Role plugins created by this project.

title¶: The human-readable project title.

url¶: The project’s public URL.

final class betty.project.ProjectLocale¶

Bases: Data[ObjectDefinition], HasProps

A locale to use for a project.

betty.project:ProjectLocale

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

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

locale¶: The locale.

betty.project.default_lifetime_threshold: Final[int] = 123¶

The default age by which people are presumed dead.

This is based on Jeanne Louise Calment who is the oldest verified person to ever have lived.