Skip to content

API reference

Generated from the library's docstrings. Everything here is imported from odouche, and nothing else is public: see Stability.

Client

odouche.Client

Client(
    session: Secret | None = None,
    *,
    read_only: bool = False,
)

Asks Odoo.sh on behalf of one session.

With no argument the session is the one in the environment, then the one stored by login. A tool that keeps sessions itself passes its own, which is never stored. Raises NoSessionError when there is none, SessionExpiredError when the stored one has passed its max age and KeyringUnavailableError when the keyring cannot be read.

Every call raises SessionExpiredError when Odoo.sh rejects the session, after deleting it if it is the stored one. Nothing is cached: each call asks Odoo.sh. Use the client as a context manager, or call close.

With read_only, a call that changes state on Odoo.sh raises ReadOnlyError and sends nothing.

session property

session: SessionInfo

Where the session came from and when it passes its max age. Odoo.sh is not asked.

read_only property

read_only: bool

Whether the client refuses the calls that change state on Odoo.sh.

close

close() -> None

Close the connections.

identity

identity() -> Identity

Return the user the session belongs to, which also tells that Odoo.sh still accepts it.

projects

projects() -> list[Project]

List the projects the session's user can reach.

project_overview

project_overview(project: Project | str) -> ProjectOverview

Return a project's overview, given as a Project or by its name.

Its subscription, Odoo version, production build and branches by stage come from the requests its page sends, for its info and its branches, and its region from the projects. Its storage, workers and staging branches come from its settings, a fourth request, sent only when the session's user is an admin of the project, as the page shows them to an admin only: otherwise hosting is None. Only reads. Every token and code in the answers is dropped unread. Raises NotFoundError when the project is not one the session's user can reach, and PermissionDeniedError when Odoo.sh refuses its branches or its settings.

project_settings

project_settings(project: Project | str) -> ProjectSettings

Return a project's settings, as its Settings page shows them, given as a Project or by its name.

Asks Odoo.sh twice, for the project's info then its settings, and only reads. Odoo.sh shows the settings to a project's admins only: anyone else gets PermissionDeniedError before the second request. A setting whose value the library does not know, or an allowed entry that is neither an address nor a network, raises UpstreamChangedError naming the field. Every token and code in the answers, and a submodule URL's credentials, are dropped unread. Raises NotFoundError when the project is not one the session's user can reach.

change_project_settings

change_project_settings(
    project: Project | str, change: ProjectSettingsChange
) -> SettingsOutcome[ProjectSettings]

Change state on Odoo.sh: set the settings change gives on a project, and return its settings before and after.

Only those that differ are sent, in one request: the others keep their value. The allow list is sent whole, as the page sends it: each entry kept as written, those removed left out, the addresses added at the end. A setting the page disables, hides or refuses, given the settings after the change, raises SettingsConflictError before the request.

Sent once. Raises OutcomeUnknownError when Odoo.sh did not confirm it, or the settings read back do not show it, ReadOnlyError on a read-only client, and PermissionDeniedError for a user who is not an admin of the project, before any change. Another setting Odoo.sh moved along is in the outcome's moved. Asks Odoo.sh four times, twice when nothing differs.

check_project_settings_change

check_project_settings_change(
    current: ProjectSettings, change: ProjectSettingsChange
) -> ProjectSettingsChange | None

Return the part of change that differs from current, or None, and raise as change_project_settings would.

current is the project's settings, as project_settings reads them. A timeout's unit and bounds are not part of them: change_project_settings checks those. Odoo.sh is not asked and nothing changes, on a read-only client too: call it before asking the user.

audit_log

audit_log(
    project: Project | str,
    *,
    limit: int = DEFAULT_LIMIT,
    timeout: float,
) -> Generator[AuditEntry]

Yield the entries of a project's audit log, given as a Project or by its name, newest first.

At most limit entries are yielded. Odoo.sh has no paging: one request answers the last 30 days whole, sent at the first read, and an answer over 16 MiB raises OdoucheError unread. Odoo.sh shows the log to a project's admins only: anyone else gets PermissionDeniedError before it is asked. An action the library does not know is AuditKind.UNKNOWN. Only reads. Raises StreamTimeoutError when the requests are not answered within timeout seconds, and NotFoundError when the project is not one the session's user can reach.

members

members(project: Project | str) -> list[ProjectMember]

List the members of a project, given as a Project or by its name, with the role of each.

They come in the order Odoo.sh answers them. Asks Odoo.sh twice, for the project's info then its settings, and only reads. Odoo.sh lists the members to a project's admins only: anyone else gets PermissionDeniedError before the second request. A role the library does not know raises UpstreamChangedError naming the field. Every token and code in the answers is dropped unread. Raises NotFoundError when the project is not one the session's user can reach.

add_member

add_member(
    project: Project | str,
    login: str,
    role: MemberRole = DEVELOPER,
) -> ProjectMember

Change state on Odoo.sh: add the GitHub user login to a project as role, and return them read back.

The project is given as a Project or by its name. Odoo.sh sends them no invitation. A login that breaks GitHub's rule for a new account, or a role that is not one, raises ValueError before any request. The members are read first: a user already among them, by login in any case or by GitHub number under another login, raises MemberRefusedError. The login is then looked up as the page does, for an exact match: none raises NotFoundError.

Sent once. Raises OutcomeUnknownError when Odoo.sh did not confirm it or the member read back is missing or has another role, ReadOnlyError on a read-only client, and PermissionDeniedError for a user who is not an admin of the project, or when Odoo.sh's grant on GitHub does not allow the lookup. Asks Odoo.sh five times.

check_add_member staticmethod

check_add_member(
    login: str,
    role: MemberRole,
    current: Sequence[ProjectMember] | None = None,
) -> None

Raise as add_member would for login and role, and with current, the members, for a login among them.

Odoo.sh is not asked and nothing changes. It needs no client: call it on the class before one is opened.

set_member_role

set_member_role(
    project: Project | str,
    member: ProjectMember | str,
    role: MemberRole,
) -> ProjectMember

Change state on Odoo.sh: give a member of a project the role role, and return them read back.

The project is given as a Project or by its name, the member as a ProjectMember or by their login in any case. The members are read first: one not among them raises NotFoundError, and one that already has role is returned with nothing sent. Lowering an admin when no other admin who has logged in remains raises MemberRefusedError. An admin who lowers their own role is read back from the project's info, as the members are then closed to them.

Sent once. Raises OutcomeUnknownError when Odoo.sh did not confirm it or the role read back is another, ReadOnlyError on a read-only client, and PermissionDeniedError for a user who is not an admin of the project. Asks Odoo.sh four times, twice when nothing changes.

check_member_role

check_member_role(
    current: Sequence[ProjectMember],
    member: ProjectMember | str,
    role: MemberRole,
) -> ProjectMember

Return the member of current, the members, that member names, and raise as set_member_role would.

One whose role is already role is one set_member_role sends nothing for. Odoo.sh is not asked and nothing changes, on a read-only client too.

branches

branches(project: Project | str) -> list[Branch]

List the branches of a project, given as a Project or by its name.

They come in the order Odoo.sh answers them, which is not by name or by stage. Raises NotFoundError when the project is not among those the session's user can reach, whether or not it exists, and PermissionDeniedError when Odoo.sh lists it but refuses its branches. Asks Odoo.sh twice, for the projects and then for the branches.

branch

branch(project: Project | str, name: str) -> Branch

Return the branch of a project that has that name, raising NotFoundError when it has none.

Raises as branches does, and asks Odoo.sh as often.

backups

backups(project: Project | str) -> list[Backup]

List the backups of a project, given as a Project or by its name, newest first.

They are every branch's: Odoo.sh answers a project's backups at once. A backup is named by its taken_at, which a REMOTE backup shares with the DAILY one it is a copy of. Raises NotFoundError when the project is not among those the session's user can reach. Asks Odoo.sh twice, for the projects and then for the backups.

create_backup

create_backup(
    project: Project | str,
    branch: Branch | int,
    *,
    comment: str = "",
) -> BackupRequest

Change state on Odoo.sh: ask for a manual backup of a branch's latest build.

The project is given as a Project or by its name, the branch as a Branch or by its number. Odoo.sh answers nothing about the backup: it is listed by backups about a minute later, and wait_for_backup waits for it. Odoo.sh keeps a manual backup for three days. Only a staging or a production branch is backed up: any other raises StageRefusedError before the request.

The request is sent once. Raises OutcomeUnknownError when it left and Odoo.sh did not confirm it: look at the backups before calling again. Raises ReadOnlyError on a read-only client, and NotFoundError when the branch has no build or is not the project's.

check_backup

check_backup(branch: Branch) -> None

Raise StageRefusedError when create_backup would refuse the branch for its stage.

Odoo.sh is not asked and nothing changes, on a read-only client too.

wait_for_backup

wait_for_backup(
    project: Project | str,
    request: BackupRequest,
    *,
    timeout: float,
) -> Generator[Backup | None]

Yield the backup create_backup asked for once Odoo.sh has finished it, and end.

Odoo.sh is asked for the project's backups every five seconds, then whether it is still making it, and None is yielded after each look that does not find it finished, so a caller can stop the wait between two. Odoo.sh lists a backup before it is finished, and refuses a file of it until then. Raises StreamTimeoutError after timeout seconds.

prepare_download

prepare_download(
    project: Project | str,
    backup: Backup,
    *,
    neutralized: bool = True,
    filestore: bool = True,
) -> PreparedDownload

Change state on Odoo.sh: ask it to prepare the file of a backup of a project.

The database is neutralized unless neutralized is false, which asks for the exact one, and the file holds the filestore unless filestore is false. Only the first combination has been seen. wait_for_download waits until the file is ready, and Odoo.sh keeps it for 2 hours from then.

The request is sent once, on the build the backup was taken from. Raises ValueError for a backup that is not downloadable, NotFoundError when that build is no longer among its branch's latest, OutcomeUnknownError when the request left and Odoo.sh did not confirm it, and ReadOnlyError on a read-only client.

find_download

find_download(
    project: Project | str,
    backup: Backup,
    *,
    neutralized: bool = True,
    filestore: bool = True,
) -> PreparedDownload | None

Return the file of a backup that Odoo.sh already holds, prepared with these choices, or None.

It only reads, on a read-only client too. A notification of Odoo.sh names the file, and the file is then opened once and closed, to tell it is still there. download takes what it returns, with no wait. Raises as prepare_download does before its request.

wait_for_download

wait_for_download(
    project: Project | str,
    prepared: PreparedDownload,
    *,
    timeout: float,
) -> Generator[None]

Yield None until the file prepare_download asked for is ready, and end once it is.

Odoo.sh is asked for the project's notifications every five seconds, and the file is ready when one links to it. Raises StreamTimeoutError after timeout seconds.

download

download(
    prepared: PreparedDownload,
) -> AbstractContextManager[BackupFile]

Open a prepared backup's file, to be read as it arrives. Leaving the context closes the connection.

The file is asked of its build's worker with a token Odoo.sh hands over for it, which is sent nowhere else and kept nowhere. Raises NotFoundError when the file is not ready or Odoo.sh no longer keeps it, and UpstreamUnavailableError from chunks when the connection drops before its last byte.

builds

builds(
    branch: Branch | int, *, limit: int = DEFAULT_LIMIT
) -> list[Build]

List the latest builds of a branch, given as a Branch or by its number, newest first.

At most limit builds are returned, in one request. Odoo.sh may answer fewer than asked for: it has only been seen to answer up to four, and older builds are out of reach. Raises NotFoundError when the branch is not one the session's user can reach.

build

build(branch: Branch | int, build_id: int) -> Build

Return one build of a branch by its number.

Odoo.sh has no request for a build by its number, so the build is looked for among the branch's latest. Raises NotFoundError when it is not there, which an older build is not.

Odoo.sh has no settings request for a build either: the builds answer gives only each build's operating system and Odoo version, and a new build takes its branch's settings, which branch_settings reads.

latest_build

latest_build(branch: Branch | int) -> Build | None

Return the newest build of a branch, or None when it has none.

history

history(
    branch: Branch | int,
    *,
    limit: int = PAGE,
    timeout: float,
) -> Generator[Tracking]

Yield the events of a branch, given as a Branch or by its number, newest first.

At most limit events are yielded. Odoo.sh answers them twenty at a time, and the next twenty are asked for only when the iterator is read past the last ones. That the next page is at an offset of twenty is inferred, not seen. An event read again, because a newer one pushed it down, is skipped, and a page with nothing older raises UpstreamChangedError. Raises StreamTimeoutError when a page is still to be asked for after timeout seconds, and NotFoundError when the branch is not one the session's user can reach.

branch_settings

branch_settings(branch: Branch | int) -> BranchSettings

Return a branch's settings, given as a Branch or by its number.

A setting whose value the library does not know raises UpstreamChangedError naming it, rather than passing through unchecked. Raises NotFoundError when the branch is not one the session's user can reach. Asks Odoo.sh once, and only reads.

change_branch_settings

change_branch_settings(
    branch: Branch | int, change: SettingsChange
) -> SettingsOutcome[BranchSettings]

Change state on Odoo.sh: set the settings change gives on a branch, and return its settings before and after.

Only those that differ are sent, in one request, as the page sends a section of its Settings tab: the others keep their value. The branch's stage is read again, and a setting the tab does not show in it raises StageRefusedError before the request; one it disables or hides, given the settings after the change, raises SettingsConflictError.

Sent once. Raises OutcomeUnknownError when Odoo.sh did not confirm it, or the settings read back do not show it, ReadOnlyError on a read-only client, PermissionDeniedError when refused, and NotFoundError for a branch out of reach. Another setting Odoo.sh moved along is in the outcome's moved. Asks Odoo.sh four times, twice when nothing differs.

check_settings_change

check_settings_change(
    branch: Branch,
    current: BranchSettings,
    change: SettingsChange,
) -> SettingsChange | None

Return the part of change that differs from current, or None, and raise as change_branch_settings would.

current is the branch's settings, as branch_settings reads them. Odoo.sh is not asked and nothing changes, on a read-only client too: call it before asking the user.

move_branch

move_branch(branch: Branch | int, to: Stage) -> Branch

Change state on Odoo.sh: move a branch between development and staging, and return it in its new stage.

A move to staging starts a build of the branch on a copy of production's data; a move to development drops its staging builds, which are not backed up. A production branch, a move to production, a stage the library does not know and a branch already in to raise StageRefusedError before the request. The stage that decides is read again first.

Sent once. Raises OutcomeUnknownError when Odoo.sh did not confirm it or the branch read back is not in to, ReadOnlyError on a read-only client, PermissionDeniedError when refused, and NotFoundError for a branch out of reach. Asks Odoo.sh three times. A branch that is not a number raises TypeError.

check_move

check_move(branch: Branch, to: Stage) -> None

Raise StageRefusedError when move_branch would refuse the move for the branch's stage or to.

Odoo.sh is not asked and nothing changes, on a read-only client too.

build_revision

build_revision(
    project: Project | str, build: Build
) -> BuildRevision

Return the revision a build of a project runs: its head commit, its Odoo version, and its branch's selected Odoo revision.

Odoo.sh ties no Odoo revision to a build, so the branch's is the one it has selected now, which the build may not run. Odoo.sh gives no commit for a submodule. Asks Odoo.sh twice, and a third time for the project's Odoo version when the branch has none of its own, and only reads. Raises NotFoundError when the build is no longer among its branch's latest or the project is not one the session's user can reach, and UpstreamChangedError naming a field that is not as seen.

ssh_target

ssh_target(build: Build) -> SshTarget

Return the user and the host ssh reaches a build with. Odoo.sh is not asked.

Odoo.sh accepts there the keys registered on the user's account, not the session. Raises NotFoundError when the build has no host, and UpstreamChangedError when its number or its address is not one that can be handed to ssh as it is.

panel_url

panel_url(
    project: Project | str,
    branch: Branch,
    build: Build,
    panel: Panel | str,
) -> str

Return the address of a panel of a build of a branch, for a browser to open. Odoo.sh is not asked.

The shell and the editor are on the build's own host, the monitor is the branch's on www.odoo.sh. None carries a token or the session: the browser signs in to Odoo.sh on its own. As on the page, a build has panels once it is DONE, judged from build as given, and only a staging or a production branch has a monitor, which shows its latest build. Raises NotFoundError for a build that is not done, one waiting for a worker included, or a monitor of another stage, ValueError for an unknown panel or a build of another branch, and UpstreamChangedError when the build's address is not a bare host under odoo.com.

allow_ip

allow_ip(branch: Branch | int) -> IPv4Address | IPv6Address

Change state on Odoo.sh: let the address this machine reaches it from connect with ssh.

Returns the address, which Odoo.sh takes from the connection: behind a proxy it is the proxy's. Odoo.sh says the rule lasts one hour and takes up to five minutes to apply. The branch is given as a Branch or by its number.

The request is sent once. Raises OutcomeUnknownError when it left and Odoo.sh did not confirm it, ReadOnlyError on a read-only client, and PermissionDeniedError when Odoo.sh refuses it to the session's user, as the page expects for a stage above their access.

rebuild

rebuild(branch: Branch | int) -> Build

Change state on Odoo.sh: start a new build of a branch, given as a Branch or by its number.

Returns the new build, which replaces the branch's latest one. Only a development or a staging branch is rebuilt: any other raises StageRefusedError before the request.

The request is sent once. Raises OutcomeUnknownError when it left and Odoo.sh did not confirm it, or the new build cannot be found: look at the branch before calling again, since a second call can start a second build. Raises ReadOnlyError on a read-only client, and NotFoundError when the branch is not one the session's user can reach. A branch that is not a number raises TypeError.

check_rebuild

check_rebuild(branch: Branch) -> None

Raise StageRefusedError when rebuild would refuse the branch for its stage.

Odoo.sh is not asked and nothing changes, on a read-only client too.

watch_build

watch_build(
    project: Project | str,
    build: Build,
    *,
    timeout: float,
    pulse: float | None = None,
) -> Generator[Build]

Yield a build of a project as it is now, then at each change, and end once it has finished.

A change is one of status, result or status_info. The last build yielded is the finished one, and a build that has already finished is yielded once. The watch stays on this build: a newer one on the branch ends it as DROPPED. Closing the iterator closes the connection.

With pulse, the build is also yielded unchanged, every pulse seconds at least while nothing changes. An iterator is closed only between two builds, so a caller that may have to stop the watch asks for one.

Raises StreamTimeoutError after timeout seconds, UpstreamUnavailableError when the connection fails three times in a row or Odoo.sh cannot be asked for the build, and NotFoundError when the build is not among its branch's latest, or the project is not one the session's user can reach.

logs

logs(project: Project | str, build: Build) -> list[Log]

List the logs a build of a project has, which is none while it waits for a worker.

Raises NotFoundError when the build is not among its branch's latest, or the project is not one the session's user can reach.

read_log

read_log(
    project: Project | str,
    build: Build,
    kind: LogKind | str,
    *,
    tail: int | None = None,
) -> Generator[LogLine]

Yield the lines of one log of a build, given as a LogKind or by its name.

Log content is untrusted: it is whatever a process printed, terminal escape sequences and secrets of the instance included, and it is returned unchanged.

With tail, only the last lines are yielded, out of the log's last mebibyte. A line longer than 64 KiB is cut. Closing the iterator closes the connection. Raises NotFoundError when the build has no such log.

follow_log

follow_log(
    project: Project | str,
    build: Build,
    kind: LogKind | str,
    *,
    timeout: float,
    tail: int = 0,
    offset: int | None = None,
) -> Generator[LogLine]

Yield the lines of one log of a build as they are written, until the iterator is closed.

Log content is untrusted, as in read_log.

It starts after the log's last tail lines, or at offset, which is the offset of a line read before. Odoo.sh is asked every second. Raises StreamTimeoutError after timeout seconds, which math.inf makes no limit, UpstreamUnavailableError when a failed request is not answered after two more tries, and NotFoundError when the build has no such log.

mails

mails(
    project: Project | str,
    branch: Branch,
    build: Build,
    *,
    limit: int = DEFAULT_LIMIT,
) -> list[Mail]

List the mails a build of a development or a staging branch caught instead of sending, newest first.

At most limit mails, out of the latest 1000 the worker keeps. They are asked of the build's worker with the project's token, never with the session, and none while the build waits for a worker. A mail's fields are untrusted: the build's code or its data wrote them. Raises NotFoundError for a branch of another stage, before any request, or a build not among its branch's latest, ValueError for a build of another branch, and OdoucheError when the worker's list is over 16 MiB, which is not read.

mail

mail(
    project: Project | str,
    branch: Branch,
    build: Build,
    mail_id: str,
) -> MailContent

Return one mail a build caught, by the id that mails gives it, with its text and its attachments' names.

Its content is untrusted and never rendered: an HTML body is turned into text, and nothing in it is followed. A body is cut at 1 MiB as UTF-8, a header at 65536 characters and the parts at 1000, every MIME part counted, containers included. A mail over 16 MiB is not read. Each is truncated. Raises NotFoundError for a mail the build did not catch, and as mails does, and OdoucheError when the worker's list is over 16 MiB.

odouche.Secret

Secret(value: str)

A sensitive string, such as an Odoo.sh session, that cannot print itself.

repr(), str() and format() return a placeholder, and pickling or copying raises TypeError. The value leaves only through expose_secret.

expose_secret

expose_secret() -> str

Return the wrapped value.

Logging in and out

odouche.login

login(
    *,
    ask: Callable[[], Secret] | None = None,
    notify: Callable[[LoginStep], None] = lambda _: None,
    timeout: float = 300,
) -> None

Log in to Odoo.sh and store the session in the keyring, replacing the stored one.

The user signs in with GitHub in a browser launched for the login, with a profile that is deleted when it ends. Where no browser can be launched, ask is called for the session_id cookie of www.odoo.sh: prompt for it without echo and return it wrapped in a Secret. notify is called with each LoginStep. The function itself neither prints nor prompts.

The session is stored once Odoo.sh has answered one request sent with it. Raises LoginTimeoutError when the sign-in has been waited for timeout seconds, LoginError when no session is obtained or Odoo.sh refuses the one pasted, and KeyringUnavailableError, before anything is asked of the user, when there is nowhere to store one or the keyring has not been unlocked within timeout seconds.

odouche.LoginStep

Bases: Enum

What a login is waiting for, for a frontend to say in its own words.

KEYRING class-attribute instance-attribute

KEYRING = 'keyring'

The keyring is being checked, and may be showing a dialog to be unlocked.

BROWSER class-attribute instance-attribute

BROWSER = 'browser'

A browser window is open on the Odoo.sh login, for the user to sign in with GitHub.

PASTE class-attribute instance-attribute

PASTE = 'paste'

No browser can be launched here: the session_id cookie is about to be asked for.

odouche.logout

logout(
    session: Secret | None = None,
    *,
    invalidate_given: bool = False,
) -> LogoutResult

Log out of Odoo.sh: end the stored session there, and delete it from the keyring.

The stored session is deleted even when Odoo.sh cannot be asked to end it. The result's failure then says why, and a copy of the session works until Odoo.sh expires it. With no session nothing is raised. A stored one past its max age, or that cannot be read, is deleted and not ended.

A session passed or set in the environment is not the library's to delete: the result names its source, and unsetting it is left to the caller. It is ended on Odoo.sh only with invalidate_given, since others may be using it. The stored session is then left as it is.

Raises NoSessionError when the session passed or set in the environment is not a cookie value, and KeyringUnavailableError when the keyring cannot be read or the session not deleted. When it is not deleted, the message says whether Odoo.sh ended it.

odouche.LogoutResult dataclass

LogoutResult(
    source: SessionSource | None,
    deleted: bool,
    invalidated: bool,
    failure: OdoucheError | None,
)

What a logout did.

source instance-attribute

source: SessionSource | None

Where the session came from, or None when there was none to log out of.

deleted instance-attribute

deleted: bool

Whether the stored session was deleted. One passed or set in the environment never is.

invalidated instance-attribute

invalidated: bool

Whether Odoo.sh has ended the session, so that a copy of it no longer works.

failure instance-attribute

failure: OdoucheError | None

Why Odoo.sh could not be asked to end the session, or None.

Session

odouche.Identity dataclass

Identity(
    user_id: int,
    name: str | None,
    username: str,
    email: str | None,
    session: SessionInfo,
)

The user a session belongs to, as Odoo.sh reports them.

user_id instance-attribute

user_id: int

The number Odoo.sh gives the user.

name instance-attribute

name: str | None

The user's display name, when Odoo.sh gives one.

username instance-attribute

username: str

The user's GitHub login.

email instance-attribute

email: str | None

The user's email address, when Odoo.sh gives one. It is personal data, carried as given.

session instance-attribute

session: SessionInfo

The session that was asked with.

odouche.SessionInfo dataclass

SessionInfo(
    source: SessionSource,
    stored_at: datetime | None,
    expires_at: datetime | None,
)

What is known of a session without asking Odoo.sh. It never holds the session.

source instance-attribute

source: SessionSource

Where the session came from.

stored_at instance-attribute

stored_at: datetime | None

When the login stored it, in UTC, or None when it is not the stored one.

expires_at instance-attribute

expires_at: datetime | None

When it passes the client-side max age, in UTC, or None when it is not the stored one.

odouche.SessionSource

Bases: StrEnum

Where a session came from.

ARGUMENT class-attribute instance-attribute

ARGUMENT = 'argument'

The caller passed it.

odouche.SESSION_ENV module-attribute

SESSION_ENV = 'ODOUCHE_SESSION'

The environment variable a session is read from. It wins over the keyring and is never stored.

odouche.KEYRING_SERVICE module-attribute

KEYRING_SERVICE = 'odouche'

The service the session is stored under in the OS keyring.

odouche.KEYRING_ENTRY module-attribute

KEYRING_ENTRY = 'session'

The name of the keyring entry, which holds the session and the time it was stored.

Projects, branches and builds

odouche.Project dataclass

Project(id: int, name: str, repository: str, url: str)

An Odoo.sh project the session's user can reach.

id instance-attribute

id: int

The number Odoo.sh gives the project.

name instance-attribute

name: str

The project's name on Odoo.sh, as in the address of its page.

repository instance-attribute

repository: str

The GitHub repository the project builds, as owner/name.

url instance-attribute

url: str

The address of the project's page on Odoo.sh.

odouche.ProjectOverview dataclass

ProjectOverview(
    id: int,
    name: str,
    repository: str,
    subscription: Subscription,
    subscription_name: str,
    trial_days_left: int | None,
    odoo_version: str,
    region: str,
    dedicated: bool,
    production_build: ProductionBuild | None,
    access_level: str,
    hosting: ProjectHosting | None,
    stages: tuple[StageCount, ...],
    branches: tuple[BranchSummary, ...],
)

What a project's page and its Settings page tell about it. No token or code is part of it.

id instance-attribute

id: int

The number Odoo.sh gives the project.

name instance-attribute

name: str

The project's name on Odoo.sh, as in the address of its page.

repository instance-attribute

repository: str

The GitHub repository the project builds, as owner/name.

subscription instance-attribute

subscription: Subscription

The state of the project's subscription.

subscription_name instance-attribute

subscription_name: str

What Odoo.sh calls that state, such as valid.

trial_days_left instance-attribute

trial_days_left: int | None

The days left of a trial given by a partnership code, or None when there is none.

odoo_version instance-attribute

odoo_version: str

The project's Odoo version, such as 19.0.

region instance-attribute

region: str

Where the project is hosted, in Odoo.sh's own words, such as Europe.

dedicated instance-attribute

dedicated: bool

Whether the project pays for a dedicated server.

production_build instance-attribute

production_build: ProductionBuild | None

The build the production branch serves, or None when there is none.

access_level instance-attribute

access_level: str

What the session's user is on the project, in Odoo.sh's own words, such as admin or developer.

hosting instance-attribute

hosting: ProjectHosting | None

Its storage, workers and staging branches, or None when the session's user is not an admin of the project: Odoo.sh shows them to an admin only, and they are not asked otherwise.

stages instance-attribute

stages: tuple[StageCount, ...]

The branches in production, staging and development, each counted even at 0, then in each stage the library does not know, by name.

branches instance-attribute

branches: tuple[BranchSummary, ...]

The branches with their last builds, in the order Odoo.sh answers them.

odouche.Subscription

Bases: StrEnum

The state of a project's subscription, as Odoo.sh reports it.

NON_STANDARD class-attribute instance-attribute

NON_STANDARD = 'non_standard'

A subscription Odoo.sh calls custom, which its page shows as non-standard.

EXPIRED class-attribute instance-attribute

EXPIRED = 'expired'

A subscription Odoo.sh calls invalid, which its page shows as expired.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

A state the library does not know. The overview's subscription_name holds what Odoo.sh calls it.

odouche.ProductionBuild dataclass

ProductionBuild(id: int, branch_name: str, url: str)

The build a project's production branch serves.

id instance-attribute

id: int

The number Odoo.sh gives the build.

branch_name instance-attribute

branch_name: str

The git branch.

url instance-attribute

url: str

The address of the production database.

odouche.ProjectHosting dataclass

ProjectHosting(
    storage_used_bytes: int,
    storage_quota_bytes: int,
    workers: int,
    staging_branches: int,
)

What a project's subscription allows and how much storage it uses, as its Settings page shows them.

storage_used_bytes instance-attribute

storage_used_bytes: int

The storage the project is accounted for, in bytes.

storage_quota_bytes instance-attribute

storage_quota_bytes: int

The storage the subscription allows, in bytes.

workers instance-attribute

workers: int

The workers of the production branch.

staging_branches instance-attribute

staging_branches: int

The staging branches the subscription allows.

odouche.StageCount dataclass

StageCount(stage: Stage, stage_name: str, count: int)

How many branches of a project sit in one stage.

stage instance-attribute

stage: Stage

The stage.

stage_name instance-attribute

stage_name: str

What Odoo.sh calls that stage, such as dev.

count instance-attribute

count: int

The branches in it, which can be 0.

odouche.BranchSummary dataclass

BranchSummary(
    branch: Branch, last_build: TrackedBuild | None
)

A branch of a project, with its last build.

branch instance-attribute

branch: Branch

The branch.

last_build instance-attribute

last_build: TrackedBuild | None

Its last build, or None when it has none.

odouche.ProjectSettings dataclass

ProjectSettings(
    name: str,
    odoo_domain_blocked: bool,
    session_lifetime: SessionLifetime,
    public: bool,
    commit_statuses_suspended: bool,
    deploy_key_writable: bool,
    submodules: tuple[Submodule, ...],
    hosting: ProjectHosting,
    dedicated: bool,
    http_timeout_seconds: int,
    cron_timeout_seconds: int,
    module_install: ModuleInstall,
    modules: tuple[str, ...],
    tests: BuildTests,
    test_tags: str | None,
    demo_data: bool,
    ai_agent: AiAgent,
    ip_allow_list: tuple[
        IPv4Address
        | IPv6Address
        | IPv4Network
        | IPv6Network,
        ...,
    ],
)

A project's settings, as its Settings page shows them to an admin. No token or code is part of it.

module_install to ai_agent are the development defaults: the new build options of a development branch whose own settings say to apply them.

name instance-attribute

name: str

The project's name on Odoo.sh, as in the address of its page.

odoo_domain_blocked instance-attribute

odoo_domain_blocked: bool

Whether the production database is unreachable on its odoo.com domain, only on its custom ones.

session_lifetime instance-attribute

session_lifetime: SessionLifetime

How long a member's session on Odoo.sh can last while working on the project.

public instance-attribute

public: bool

Whether its Builds page is open to visitors, who can then connect to its development builds.

commit_statuses_suspended instance-attribute

commit_statuses_suspended: bool

Whether Odoo.sh stopped sending commit statuses to GitHub, as the check of their token failed.

deploy_key_writable instance-attribute

deploy_key_writable: bool

Whether the project's deploy key may push to its repository.

submodules instance-attribute

submodules: tuple[Submodule, ...]

Its private submodules, in the order Odoo.sh answers them.

hosting instance-attribute

hosting: ProjectHosting

Its storage, workers and staging branches.

dedicated instance-attribute

dedicated: bool

Whether the project pays for a dedicated server. The two timeouts are changed only on one.

http_timeout_seconds instance-attribute

http_timeout_seconds: int

How long an HTTP request runs before a worker is stopped.

cron_timeout_seconds instance-attribute

cron_timeout_seconds: int

How long a scheduled action runs before it is stopped.

module_install instance-attribute

module_install: ModuleInstall

Which modules a new development build installs.

modules instance-attribute

modules: tuple[str, ...]

The modules stored for LISTED, given whatever module_install is. They apply only to LISTED.

tests instance-attribute

tests: BuildTests

Which tests a new development build runs.

test_tags instance-attribute

test_tags: str | None

The Odoo test tags stored for TAGS, given whatever tests is. They apply only to TAGS.

demo_data instance-attribute

demo_data: bool

Whether a new development build loads demonstration data.

ai_agent instance-attribute

ai_agent: AiAgent

The agent the AI tab of a development branch runs.

ip_allow_list instance-attribute

ip_allow_list: tuple[
    IPv4Address | IPv6Address | IPv4Network | IPv6Network,
    ...,
]

The addresses allowed SSH, and PostgreSQL on a dedicated server, to its production and staging builds, in the order the Settings page lists them: an entry with a / as a network, any other as an address.

odouche.ProjectSettingsChange dataclass

ProjectSettingsChange(
    *,
    session_lifetime: SessionLifetime | None = None,
    public: bool | None = None,
    http_timeout_seconds: int | None = None,
    cron_timeout_seconds: int | None = None,
    module_install: ModuleInstall | None = None,
    modules: tuple[str, ...] | None = None,
    tests: BuildTests | None = None,
    test_tags: str | None = None,
    demo_data: bool | None = None,
    ai_agent: AiAgent | None = None,
    allow_ips: tuple[IPv4Address, ...] | None = None,
    disallow_ips: tuple[
        IPv4Address
        | IPv6Address
        | IPv4Network
        | IPv6Network,
        ...,
    ]
    | None = None,
)

Settings to change on a project, named as in ProjectSettings: a field left None keeps its value on Odoo.sh.

The allow list is changed by entry, never replaced: allow_ips adds IPv4 addresses, and disallow_ips removes entries as ProjectSettings.ip_allow_list reads them. Raises ValueError when no field is given, for a timeout of 0 or less, an allow list field that is empty or names an entry twice, an entry in both, an address to allow that is unspecified, loopback, multicast, link-local or reserved, and as SettingsChange does for modules and test tags. Raises TypeError for a value of another type, an address to allow that is not an IPv4Address included.

ACCESS class-attribute

ACCESS: frozenset[str] = frozenset(
    {
        "session_lifetime",
        "public",
        "allow_ips",
        "disallow_ips",
    }
)

The fields that change who can reach the project or for how long.

session_lifetime class-attribute instance-attribute

session_lifetime: SessionLifetime | None = None

How long a member's session can last while working on the project.

public class-attribute instance-attribute

public: bool | None = None

Whether the Builds page is open to visitors.

http_timeout_seconds class-attribute instance-attribute

http_timeout_seconds: int | None = None

How long an HTTP request runs before a worker is stopped, in seconds, a whole number of the page's unit (minutes). Dedicated server only.

cron_timeout_seconds class-attribute instance-attribute

cron_timeout_seconds: int | None = None

How long a scheduled action runs before it is stopped, in seconds, a whole number of the page's unit (minutes). Dedicated server only.

module_install class-attribute instance-attribute

module_install: ModuleInstall | None = None

Which modules a new development build installs.

modules class-attribute instance-attribute

modules: tuple[str, ...] | None = None

The modules a new development build installs with LISTED.

tests class-attribute instance-attribute

tests: BuildTests | None = None

Which tests a new development build runs.

test_tags class-attribute instance-attribute

test_tags: str | None = None

The Odoo test tags TAGS runs. An empty text clears them.

demo_data class-attribute instance-attribute

demo_data: bool | None = None

Whether a new development build loads demonstration data.

ai_agent class-attribute instance-attribute

ai_agent: AiAgent | None = None

The agent the AI tab of a development branch runs.

allow_ips class-attribute instance-attribute

allow_ips: tuple[IPv4Address, ...] | None = None

The addresses to add to the IP allow list.

disallow_ips class-attribute instance-attribute

disallow_ips: (
    tuple[
        IPv4Address
        | IPv6Address
        | IPv4Network
        | IPv6Network,
        ...,
    ]
    | None
) = None

The entries to remove from the IP allow list.

given

given() -> dict[str, object]

Return the settings given, by name, in the order of the fields.

access

access() -> tuple[str, ...]

Return the fields given that change who can reach the project, in the order of the fields.

odouche.SessionLifetime

Bases: StrEnum

How long a member's session on Odoo.sh can last while working on a project.

AUTO class-attribute instance-attribute

AUTO = 'auto'

As Odoo.sh sees fit, never over 8 days.

odouche.Submodule dataclass

Submodule(
    id: int, url: str, fingerprint: str, public_key: str
)

A private Git submodule of a project, with the deploy key Odoo.sh fetches it with.

id instance-attribute

id: int

The number Odoo.sh gives it.

url instance-attribute

url: str

Its repository, such as git@github.com:owner/name.git, without a query, a fragment or user information, which ends at the last @ before the path. A Unix user name that is no token's, such as git, is kept in an ssh URL or an scp-like user@host:path. Empty when what is left of a URL with // is not a host and a port, as it could still hold part of a password.

fingerprint instance-attribute

fingerprint: str

The fingerprint of the deploy key, such as SHA256:....

public_key instance-attribute

public_key: str

The public half of the deploy key, as an OpenSSH public key line, which the repository is given.

odouche.AuditEntry dataclass

AuditEntry(
    logged_at: datetime,
    author: str,
    kind: AuditKind,
    kind_name: str,
    stage: Stage | None,
    details: str,
    succeeded: bool,
)

One entry of a project's audit log: who did what, when, and on which stage.

logged_at instance-attribute

logged_at: datetime

When it was done, in UTC.

author instance-attribute

author: str

Who did it, as a GitHub login. It is another person's personal data, carried as given, which can hold control characters.

kind instance-attribute

kind: AuditKind

What was done.

kind_name instance-attribute

kind_name: str

What Odoo.sh calls it, such as Open Shell, cut to 64 characters. Text Odoo.sh sends, not checked.

stage instance-attribute

stage: Stage | None

The stage of the branch it was done on, or None for an action on the project.

details instance-attribute

details: str

What Odoo.sh adds about it, often empty. It holds addresses, logins and what an SSH client says of itself: untrusted text, carried as given, which can hold control characters.

succeeded instance-attribute

succeeded: bool

Whether it succeeded.

odouche.AuditKind

Bases: StrEnum

What a project's audit log records someone did.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

An action the library does not know. The entry's kind_name holds what Odoo.sh calls it.

odouche.ProjectMember dataclass

ProjectMember(
    id: int,
    login: str,
    name: str,
    role: MemberRole,
    github_id: int,
    pending_login: bool,
)

A member of a project, as its Settings page lists them to an admin. Odoo.sh gives no member's email.

id instance-attribute

id: int

The number of the membership, not of the person.

login instance-attribute

login: str

Their GitHub login. It is another person's personal data, carried as given, which can hold control characters.

name instance-attribute

name: str

What Odoo.sh calls them, the login in every member seen. Personal data as login is, carried as given.

role instance-attribute

role: MemberRole

What they may do on the project.

github_id instance-attribute

github_id: int

Their GitHub user number, which stays when they rename their login.

pending_login instance-attribute

pending_login: bool

Whether they were invited and have not logged in to Odoo.sh yet.

odouche.MemberRole

Bases: StrEnum

What a member may do on a project, declared lowest first as Odoo.sh ranks them.

Compare roles by rank, never with <: a StrEnum compares its values as strings.

rank property

rank: int

Its place among the roles, 0 for the lowest. A higher role reaches all a lower one does.

odouche.Branch dataclass

Branch(id: int, name: str, stage: Stage, stage_name: str)

A branch of an Odoo.sh project.

id instance-attribute

id: int

The number Odoo.sh gives the branch.

name instance-attribute

name: str

The git branch.

stage instance-attribute

stage: Stage

The stage the branch sits in now.

stage_name instance-attribute

stage_name: str

What Odoo.sh calls that stage, such as dev.

odouche.Stage

Bases: StrEnum

The stage a branch sits in on Odoo.sh.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

A stage the library does not know. The branch's stage_name holds what Odoo.sh calls it.

odouche.Build dataclass

Build(
    id: int,
    name: str,
    branch_id: int,
    branch_name: str,
    commit: Commit,
    status: BuildStatus,
    status_name: str,
    result: BuildResult | None,
    result_name: str | None,
    status_info: str | None,
    started_at: datetime | None,
    url: str | None,
)

What Odoo.sh made of a commit on a branch.

id instance-attribute

id: int

The number Odoo.sh gives the build.

name instance-attribute

name: str

The build's name on Odoo.sh, which is not derivable from its branch.

branch_id instance-attribute

branch_id: int

The number of the branch the build belongs to.

branch_name instance-attribute

branch_name: str

The git branch.

commit instance-attribute

commit: Commit

The commit the build was made from.

status instance-attribute

status: BuildStatus

Where the build is in its life.

status_name instance-attribute

status_name: str

What Odoo.sh calls that status, such as progress.

result instance-attribute

result: BuildResult | None

How the build ended, or None when Odoo.sh gives none. finished says whether it ended.

result_name instance-attribute

result_name: str | None

What Odoo.sh calls that result, such as success.

status_info instance-attribute

status_info: str | None

What the build is doing, in Odoo.sh's own words, such as Installing: account.

started_at instance-attribute

started_at: datetime | None

When a worker took the build, in UTC, or None while it waits for one.

url instance-attribute

url: str | None

The address of the build's database, when it has one.

finished property

finished: bool

Whether the build has ended, whatever its result.

DONE and DROPPED are the ended statuses Odoo.sh has been seen to give. SKIPPED and KILLED are counted as ended from their names alone. An unknown status is not finished.

odouche.BuildStatus

Bases: StrEnum

Where a build is in its life on Odoo.sh. How it ended is its BuildResult.

DROPPED class-attribute instance-attribute

DROPPED = 'dropped'

What a build becomes when a newer one replaces it.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

A status the library does not know. The build's status_name holds what Odoo.sh calls it.

odouche.BuildResult

Bases: StrEnum

How a build ended.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

A result the library does not know. The build's result_name holds what Odoo.sh calls it.

odouche.SshTarget dataclass

SshTarget(user: str, host: str)

Where ssh reaches a build: the user to log in as and the host.

user instance-attribute

user: str

The user on the build's host, which is the build's number.

host instance-attribute

host: str

The build's own host.

odouche.Panel

Bases: StrEnum

A page of a build that Odoo.sh opens in a browser.

MONITOR class-attribute instance-attribute

MONITOR = 'monitor'

The branch's Grafana dashboard on www.odoo.sh, for a staging or a production branch.

SHELL class-attribute instance-attribute

SHELL = 'shell'

A terminal in the build's container, on its own host.

EDITOR class-attribute instance-attribute

EDITOR = 'editor'

The code editor of the build's container, on its own host.

odouche.Commit dataclass

Commit(
    hash: str,
    message: str,
    author: str,
    timestamp: datetime,
    url: str,
)

The commit a build was made from, as Odoo.sh reports it.

hash instance-attribute

hash: str

The commit's full hash.

message instance-attribute

message: str

The whole commit message.

author instance-attribute

author: str

The author's name. It is another person's personal data, carried as Odoo.sh gives it.

timestamp instance-attribute

timestamp: datetime

When the commit was made, in UTC.

url instance-attribute

url: str

The address of the commit on GitHub.

odouche.BuildRevision dataclass

BuildRevision(
    build_id: int,
    build_name: str,
    branch_name: str,
    commit: Commit,
    odoo_version: str,
    branch_odoo_revision: OdooRevision | None,
)

What a build runs, as far as Odoo.sh says.

Odoo.sh gives no commit for a submodule of the project's repository, so there is none here, and nothing here says whether the repository has any.

build_id instance-attribute

build_id: int

The number Odoo.sh gives the build.

build_name instance-attribute

build_name: str

The build's name on Odoo.sh.

branch_name instance-attribute

branch_name: str

The git branch.

commit instance-attribute

commit: Commit

The head commit of the project's repository, with its full hash.

odoo_version instance-attribute

odoo_version: str

The Odoo version the build was made with, such as 19.0.

branch_odoo_revision instance-attribute

branch_odoo_revision: OdooRevision | None

The Odoo revision the branch has selected now, or None when Odoo.sh gives none.

Odoo.sh ties no revision to a build, so it is not proven to be the one the build runs.

odouche.OdooRevision dataclass

OdooRevision(
    id: int,
    version: str,
    pinned: bool,
    refs: tuple[OdooRef, ...],
)

A weekly revision of Odoo's own repositories, as a branch has selected it.

id instance-attribute

id: int

The number Odoo.sh gives the revision, which BranchSettings.odoo_revision_id holds when it is pinned.

version instance-attribute

version: str

The Odoo version, such as 19.0.

pinned instance-attribute

pinned: bool

Whether the branch pins this revision. Otherwise it is the latest of its version, and moves on.

refs instance-attribute

refs: tuple[OdooRef, ...]

The commit of each repository, in the order Odoo.sh gives them.

odouche.OdooRef dataclass

OdooRef(repository: str, commit_hash: str, url: str)

The commit of one of Odoo's own repositories in a weekly Odoo revision.

repository instance-attribute

repository: str

What Odoo.sh calls the repository, such as enterprise.

commit_hash instance-attribute

commit_hash: str

The commit's full hash.

url instance-attribute

url: str

The repository's address.

odouche.Tracking dataclass

Tracking(
    id: int,
    kind: TrackingKind,
    kind_name: str,
    created_at: datetime,
    build: TrackedBuild | None,
    commits: tuple[PushedCommit, ...],
    pusher: str | None,
    source_stage: Stage | None,
    target_stage: Stage | None,
)

One event of a branch's history: a push, a rebuild or a move between stages.

id instance-attribute

id: int

The number Odoo.sh gives the event.

kind instance-attribute

What happened.

kind_name instance-attribute

kind_name: str

What Odoo.sh calls it, such as push.

created_at instance-attribute

created_at: datetime

When it happened, in UTC.

build instance-attribute

build: TrackedBuild | None

The build it made, or None, as for the stage event that created the branch.

commits instance-attribute

commits: tuple[PushedCommit, ...]

The commits of a push, in the order Odoo.sh gives them. Empty for any other event.

pusher instance-attribute

pusher: str | None

Who pushed, as Odoo.sh names them. It is another person's personal data, carried as given.

source_stage instance-attribute

source_stage: Stage | None

The stage a branch moved from, or None, as for one just created or any event but a move.

target_stage instance-attribute

target_stage: Stage | None

The stage a branch moved to or was created in, or None for any event but a stage one.

odouche.TrackingKind

Bases: StrEnum

What happened to a branch, as its history on Odoo.sh records it.

STAGE class-attribute instance-attribute

STAGE = 'stage'

The branch was created in a stage or moved to another.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

An event the library does not know. The tracking's kind_name holds what Odoo.sh calls it.

odouche.TrackedBuild dataclass

TrackedBuild(
    id: int,
    status: BuildStatus,
    status_name: str,
    result: BuildResult | None,
    result_name: str | None,
)

A build as a summary gives it: its number, status and result, for an event of a branch's history or a branch's last build. Client.build has the rest of it.

id instance-attribute

id: int

The number Odoo.sh gives the build.

status instance-attribute

status: BuildStatus

Where the build is in its life.

status_name instance-attribute

status_name: str

What Odoo.sh calls that status, such as progress.

result instance-attribute

result: BuildResult | None

How the build ended, or None when Odoo.sh gives none.

result_name instance-attribute

result_name: str | None

What Odoo.sh calls that result, such as success.

odouche.PushedCommit dataclass

PushedCommit(hash: str, message: str, url: str)

A commit of a push, as the history gives it: with no author and no date.

hash instance-attribute

hash: str

The commit's full hash.

message instance-attribute

message: str

The whole commit message.

url instance-attribute

url: str

The address of the commit on GitHub.

odouche.BranchSettings dataclass

BranchSettings(
    push_behavior: PushBehavior,
    project_defaults: bool,
    module_install: ModuleInstall,
    modules: tuple[str, ...],
    tests: BuildTests,
    test_tags: str | None,
    demo_data: bool,
    ai_agent: AiAgent,
    odoo_version: str | None,
    odoo_revision_id: int | None,
    machine: str,
    recommended_machine: str,
    next_machine: str | None,
    domains: tuple[str, ...],
    dns_target: str | None,
)

A branch's settings, as its Settings tab shows them.

The new build options, project_defaults to ai_agent, apply to a development branch only. The project's development defaults are in ProjectSettings.

push_behavior instance-attribute

push_behavior: PushBehavior

What a new commit does.

project_defaults instance-attribute

project_defaults: bool

Whether the project's development defaults apply instead of the next six fields, which the page then disables.

module_install instance-attribute

module_install: ModuleInstall

Which modules a new build installs.

modules instance-attribute

modules: tuple[str, ...]

The modules stored for LISTED, given whatever module_install is. They apply only to LISTED.

tests instance-attribute

tests: BuildTests

Which tests a new build runs.

test_tags instance-attribute

test_tags: str | None

The Odoo test tags stored for TAGS, given whatever tests is. They apply only to TAGS.

demo_data instance-attribute

demo_data: bool

Whether a new build loads demonstration data.

ai_agent instance-attribute

ai_agent: AiAgent

The agent the AI tab runs.

odoo_version instance-attribute

odoo_version: str | None

The Odoo version, such as 19.0, or None for the project's.

odoo_revision_id instance-attribute

odoo_revision_id: int | None

The id Odoo.sh gives the pinned weekly Odoo revision, or None for the latest. Its name is not given.

machine instance-attribute

machine: str

The operating system builds run on, such as ubuntu-24.04.

recommended_machine instance-attribute

recommended_machine: str

The operating system Odoo.sh recommends.

next_machine instance-attribute

next_machine: str | None

The operating system the next commit's build moves to, or None. Only None was seen.

domains instance-attribute

domains: tuple[str, ...]

The custom domains.

dns_target instance-attribute

dns_target: str | None

The host a custom domain's CNAME record points to.

odouche.PushBehavior

Bases: StrEnum

What a new commit on a branch does.

NEW_BUILD class-attribute instance-attribute

NEW_BUILD = 'new_build'

A new build, with a new database.

UPDATE class-attribute instance-attribute

UPDATE = 'update'

The latest build is updated with the commit, and keeps its database.

odouche.ModuleInstall

Bases: StrEnum

Which modules a new build installs.

REPOSITORY class-attribute instance-attribute

REPOSITORY = 'repository'

The modules of the project's repository.

ALL class-attribute instance-attribute

ALL = 'all'

The standard Odoo modules and the repository's. The page says it turns the test suite off.

LISTED class-attribute instance-attribute

LISTED = 'listed'

The modules of the settings' modules.

odouche.BuildTests

Bases: StrEnum

Which tests a new build runs.

MODULES class-attribute instance-attribute

MODULES = 'modules'

The tests of the modules it installs.

TAGS class-attribute instance-attribute

TAGS = 'tags'

Those the settings' test_tags select.

odouche.AiAgent

Bases: StrEnum

The agent a branch's AI tab runs.

odouche.SettingsChange dataclass

SettingsChange(
    *,
    push_behavior: PushBehavior | None = None,
    project_defaults: bool | None = None,
    module_install: ModuleInstall | None = None,
    modules: tuple[str, ...] | None = None,
    tests: BuildTests | None = None,
    test_tags: str | None = None,
    demo_data: bool | None = None,
    ai_agent: AiAgent | None = None,
)

Settings to change on a branch, named as in BranchSettings: a field left None keeps its value on Odoo.sh.

Raises ValueError when no field is given, for a module name of anything but ASCII letters, digits and underscores, and for test tags of other characters than Odoo's tags have, and TypeError for a value of another type, such as a choice given as text rather than as its enum's member.

push_behavior class-attribute instance-attribute

push_behavior: PushBehavior | None = None

What a new commit does.

project_defaults class-attribute instance-attribute

project_defaults: bool | None = None

Whether the project's development defaults apply instead of the branch's own new build options.

module_install class-attribute instance-attribute

module_install: ModuleInstall | None = None

Which modules a new build installs.

modules class-attribute instance-attribute

modules: tuple[str, ...] | None = None

The modules a new build installs with LISTED.

tests class-attribute instance-attribute

tests: BuildTests | None = None

Which tests a new build runs.

test_tags class-attribute instance-attribute

test_tags: str | None = None

The Odoo test tags TAGS runs. An empty text clears them.

demo_data class-attribute instance-attribute

demo_data: bool | None = None

Whether a new build loads demonstration data.

ai_agent class-attribute instance-attribute

ai_agent: AiAgent | None = None

The agent the AI tab runs.

given

given() -> dict[str, object]

Return the settings given, by name, in the order of the fields.

odouche.SettingsOutcome dataclass

SettingsOutcome(
    before: S, after: S, moved: tuple[str, ...]
)

What a change of settings did, a branch's or a project's: the settings before and after it.

before instance-attribute

before: S

The settings read before the change.

after instance-attribute

after: S

The settings read back after it, which show every setting sent as sent.

moved instance-attribute

moved: tuple[str, ...]

The settings not sent that Odoo.sh changed along with those sent, such as the tests a new build runs once it installs every module. before and after hold their values.

Backups

odouche.Backup dataclass

Backup(
    kind: BackupKind,
    kind_name: str,
    taken_at: datetime,
    build_name: str,
    branch_name: str,
    commit_hash: str,
    downloadable: bool,
    size: int | None,
)

A backup of a project's database, on any of its branches.

kind instance-attribute

kind: BackupKind

How it was made.

kind_name instance-attribute

kind_name: str

What Odoo.sh calls that kind, such as daily.

taken_at instance-attribute

taken_at: datetime

When it was taken, in UTC, to the second. It is what names the backup to Odoo.sh.

build_name instance-attribute

build_name: str

The name of the build it was taken from.

branch_name instance-attribute

branch_name: str

The git branch of that build.

commit_hash instance-attribute

commit_hash: str

The full hash of that build's commit.

downloadable instance-attribute

downloadable: bool

Whether Odoo.sh lets it be downloaded.

size instance-attribute

size: int | None

The bytes of its compressed SQL, or None when Odoo.sh gives none, as for all but REMOTE.

odouche.BackupKind

Bases: StrEnum

How a backup was made, and where it is kept.

MANUAL class-attribute instance-attribute

MANUAL = 'manual'

Asked for on a branch, and kept for three days.

REMOTE class-attribute instance-attribute

REMOTE = 'remote'

A daily backup kept off-site. Odoo.sh does not let it be downloaded as it is.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

A kind the library does not know. The backup's kind_name holds what Odoo.sh calls it.

odouche.BackupRequest dataclass

BackupRequest(build: Build, previous: datetime | None)

A manual backup asked of Odoo.sh, which lists it about a minute later.

build instance-attribute

build: Build

The build it is taken from: its branch's latest when it was asked for.

previous instance-attribute

previous: datetime | None

When the newest manual backup of that build listed before the request was taken, which a wait looks past.

odouche.PreparedDownload dataclass

PreparedDownload(
    backup: Backup,
    build: Build,
    worker_url: str,
    neutralized: bool,
    filestore: bool,
    link: str,
    previous: int,
)

A backup's file that Odoo.sh was asked to prepare, which it keeps for 2 hours once ready.

backup instance-attribute

backup: Backup

The backup the file is made from.

build instance-attribute

build: Build

The build the backup was taken from, which the file is asked of.

worker_url instance-attribute

worker_url: str

The address of the worker that holds the build, where the file is.

neutralized instance-attribute

neutralized: bool

Whether the database is neutralized, as the page's dialog offers, rather than exact.

filestore instance-attribute

filestore: bool

Whether the file holds the filestore as well as the database.

link: str

The page's link to the file. It opens only in a browser signed in to Odoo.sh.

previous instance-attribute

previous: int

The number of the project's newest notification before the request, which a wait looks past.

odouche.BackupFile dataclass

BackupFile(size: int | None, chunks: Iterator[bytes])

A prepared backup's file as it arrives: a zip of the database's SQL, and of its filestore when asked.

size instance-attribute

size: int | None

Its bytes, or None when Odoo.sh does not say.

chunks instance-attribute

chunks: Iterator[bytes]

Its bytes as they arrive. Raises UpstreamUnavailableError when the connection drops early.

Logs

odouche.Log dataclass

Log(
    kind: LogKind,
    name: str,
    modified_at: datetime,
    size: str,
)

One of the logs a build has.

kind instance-attribute

kind: LogKind

Which log it is.

name instance-attribute

name: str

What Odoo.sh calls it, such as install.

modified_at instance-attribute

modified_at: datetime

When it was last written to, in UTC.

size instance-attribute

size: str

Its size in Odoo.sh's own words, such as 156 KB.

odouche.LogKind

Bases: StrEnum

The logs Odoo.sh keeps of a build. A build has only some of them.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

A log the library does not know. The log's name holds what Odoo.sh calls it.

odouche.LogLine dataclass

LogLine(text: str, offset: int, truncated: bool)

A line of a build's log. It is untrusted: whatever a process printed, unchanged.

text instance-attribute

text: str

The line without its newline. Bytes that are not UTF-8 are replaced.

offset instance-attribute

offset: int

The byte just past the line, which is where a follow can start again.

truncated instance-attribute

truncated: bool

Whether the line was longer than the library reads, and was cut.

odouche.Mail dataclass

Mail(
    id: str,
    date: datetime | None,
    date_text: str,
    sender: str,
    recipients: str,
    subject: str,
)

A mail a build caught instead of sending it. Every field but id is untrusted: the build's code or its data wrote it.

id instance-attribute

id: str

The worker's name for the mail, which Client.mail takes.

date instance-attribute

date: datetime | None

When the mail is dated, in UTC, or None when date_text is not a date the library reads.

date_text instance-attribute

date_text: str

The date as the worker gives it.

sender instance-attribute

sender: str

The From header, as written.

recipients instance-attribute

recipients: str

The To header, as written: every address, comma-separated.

subject instance-attribute

subject: str

The Subject header, as written.

odouche.MailContent dataclass

MailContent(
    mail: Mail,
    cc: str,
    body: str,
    attachments: tuple[MailAttachment, ...],
    truncated: bool,
)

One caught mail with its body. The body and the names are untrusted text, never rendered.

mail instance-attribute

mail: Mail

The mail as Client.mails lists it.

cc instance-attribute

cc: str

The Cc header, as written. Empty when it has none.

body instance-attribute

body: str

The plain text part, or the HTML part as text. Never rendered.

attachments instance-attribute

attachments: tuple[MailAttachment, ...]

The files attached to it.

truncated instance-attribute

truncated: bool

Whether anything was cut: the body at 1 MiB as UTF-8, a header at 65536 characters, or the parts at 1000.

The 1000 count every MIME part, containers included. Also when the mail was over 16 MiB or could not be read: then body and attachments are empty.

odouche.MailAttachment dataclass

MailAttachment(name: str, size: int)

A file attached to a caught mail. Its name is untrusted, and its content is not read.

name instance-attribute

name: str

Its file name, as the mail gives it. Empty when it has none.

size instance-attribute

size: int

Its bytes, decoded. A forwarded mail counts none: its parts are not read.

odouche.strip_line_control

strip_line_control(text: str) -> str

Remove the escape sequences from a line of text that is not ours, then the control characters but the tab.

The control characters are C0, DEL, C1 and the bidirectional ones, which can reorder what is shown. A log line, a mail or an audit entry is written by a build's code or another user: this is what a frontend applies before it shows one.

Errors

odouche.OdoucheError

OdoucheError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: Exception

Base class of every error the library raises.

odouche.NoSessionError

NoSessionError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when there is no session: none was passed, set in the environment or stored.

One that is not a session_id cookie value is none.

The user has to log in.

odouche.SessionExpiredError

SessionExpiredError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when Odoo.sh rejects the session, or when it has passed the client-side max age.

The stored session is gone and the user has to log in again.

odouche.NotFoundError

NotFoundError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when the project, branch, build or log asked for is not one the session's user can reach.

odouche.PermissionDeniedError

PermissionDeniedError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when the session is valid but is not allowed to do what was asked.

odouche.UpstreamChangedError

UpstreamChangedError(
    operation: str, field: str, *, status: int | None = None
)

Bases: OdoucheError

Raised when an answer from Odoo.sh no longer has the shape the library reads.

Odoo.sh has no public API, so this is the expected way for the library to break. It is not a mistake in the caller's input.

odouche.UpstreamUnavailableError

UpstreamUnavailableError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when Odoo.sh cannot be reached, or answers with a server error.

odouche.ReadOnlyError

ReadOnlyError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when a read-only client is asked to change state on Odoo.sh. Nothing was sent.

odouche.StageRefusedError

StageRefusedError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when a branch is in a stage, or is asked into one, the library does not change. Nothing was sent.

odouche.MemberRefusedError

MemberRefusedError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised for a change of a project's members the library does not send. Nothing was sent.

odouche.SettingsConflictError

Bases: ValueError

Raised when a change of settings gives one a Settings tab or page disables, hides or refuses, given the others after it.

Nothing was sent. It is a ValueError, as an argument the caller can correct, not an OdoucheError.

odouche.OutcomeUnknownError

OutcomeUnknownError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when a state-changing request was sent and what Odoo.sh did with it is not known.

Look at Odoo.sh before trying again: the request is never repeated, since it may have been carried out.

odouche.StreamTimeoutError

StreamTimeoutError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when a stream is still open at its timeout. Nothing says Odoo.sh is unavailable.

odouche.KeyringUnavailableError

KeyringUnavailableError(
    message: str = _NO_KEYRING,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when no accepted keyring backend is available to store the session, or it stays locked.

Nothing was persisted, unless the message says a write did not finish. The message names the ways out.

odouche.LoginError

LoginError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when a login ends without a session: none could be captured, or Odoo.sh refused it.

Nothing was stored, and the session stored before the login is untouched.

odouche.LoginTimeoutError

LoginTimeoutError(
    message: str,
    *,
    operation: str | None = None,
    status: int | None = None,
)

Bases: OdoucheError

Raised when nobody completes the browser login before its timeout.

Nothing was stored, and the session stored before the login is untouched.

Version

odouche.__version__ module-attribute

__version__ = version('odouche')

The version of the installed odouche distribution.