Library¶
odouche is the Python client for Odoo.sh that the command-line tool and the MCP server are built
on. It is meant to be used directly in your own tools as well.
What it is designed to be¶
- Typed. The library returns typed models rather than raw Odoo.sh payloads, and ships type
information (
py.typed). - The only layer that knows Odoo.sh. Endpoints, payload shapes and anything scraped from the web interface live in one place, so an upstream change is fixed in one place.
- Synchronous. Every call is a plain function. From async code, run it in a thread, for
example with
asyncio.to_thread. - Streaming where it matters. Watching a build and following logs return iterators of typed events. Close the iterator to stop; pass a deadline to bound it.
Session¶
The session is taken from the ODOUCHE_SESSION environment variable when it is set, and from the
OS keyring otherwise. Security says where it is stored and for how long.
For headless use, such as CI, set ODOUCHE_SESSION to the session_id cookie of www.odoo.sh
from the job's secrets. The keyring is then neither read nor written, and nothing below changes.
Logging in¶
login opens a browser for the user to sign in to Odoo.sh with GitHub, then stores the session in
the keyring, replacing the one stored before.
import getpass
import odouche
def ask() -> odouche.Secret:
return odouche.Secret(getpass.getpass("session_id cookie of www.odoo.sh: "))
odouche.login(ask=ask, notify=lambda step: print(step.value), timeout=300)
- The library neither prints nor prompts.
notifyis called with aLoginStep:KEYRINGwhen the keyring is checked and may be showing a dialog to be unlocked,BROWSERwhen the window is open,PASTEwhen no browser can be launched andaskis about to be called. askreturns the pasted cookie, wrapped in aSecret. Without it, a machine with no browser to launch gets aLoginError.- The session is stored once Odoo.sh has answered one request sent with it. A login that is refused or times out leaves the stored session as it was.
- A login nobody completes raises
LoginTimeoutErroraftertimeoutseconds. - Called from the main thread, a login that
SIGTERMorSIGHUPends deletes the browser profile before the signal takes effect. - With no keyring to store the session in, or one not unlocked within
timeoutseconds,KeyringUnavailableErroris raised before the browser opens. - Outside a login, a keyring showing a dialog is waited for ten seconds, then
KeyringUnavailableErroris raised.
Logging out¶
logout ends the stored session on Odoo.sh, so that a copy of it stops working, and deletes it
from the keyring.
import odouche
result = odouche.logout()
if result.failure is not None:
print("Deleted here, but Odoo.sh could not be asked to end it:", result.failure)
It returns a LogoutResult:
| Field | Meaning |
|---|---|
source |
A SessionSource: KEYRING, ENVIRONMENT or ARGUMENT. None when there was no session. |
deleted |
Whether the stored session was deleted. |
invalidated |
Whether Odoo.sh has ended the session. |
failure |
The error that kept Odoo.sh from being asked, or None. |
- The stored session is deleted even when Odoo.sh cannot be reached.
failurethen holds the error, and the session works until Odoo.sh expires it. - With no session, nothing is asked and nothing is raised. A stored one past its max age, or that cannot be read, is deleted and not ended on Odoo.sh.
- A session from the environment or passed as
logout(session)is not deleted: unset it yourself. It is ended on Odoo.sh only withinvalidate_given=True, since a session shared between jobs would stop working for all of them. The stored session is then left as it is: unset the variable and calllogout()again to end it. - A session passed or set in the environment that is not a
session_idcookie value raisesNoSessionError. KeyringUnavailableErroris raised when the keyring cannot be read or the session not deleted. When it is not deleted, the message says whether Odoo.sh ended it.
Client¶
Client is the one object everything is asked through. It closes its connections when the block
ends.
import odouche
with odouche.Client() as client:
for project in client.projects():
print(project.name, project.repository, project.url)
- With no argument, the session is resolved as above. A tool that keeps sessions itself
passes its own,
odouche.Client(odouche.Secret(value)), which is never stored. - With no session, or a value that is not a
session_idcookie value,Client()raisesNoSessionError. - Nothing is cached: each call asks Odoo.sh.
Who is logged in¶
client.identity() asks Odoo.sh who the session belongs to, and returns an Identity. Being
answered also means the session is still valid: a rejected one raises SessionExpiredError.
| Field | Meaning |
|---|---|
user_id |
The number Odoo.sh gives the user. |
name |
The user's display name, or None. |
username |
The user's GitHub login. |
email |
The user's email address, or None. Treat it as personal data. |
session |
The SessionInfo below. |
client.session is a SessionInfo, read without asking Odoo.sh, so it works offline. It never
holds the session itself.
| Field | Meaning |
|---|---|
source |
A SessionSource: KEYRING, ENVIRONMENT or ARGUMENT. |
stored_at |
When the login stored the session. None unless it came from the keyring. |
expires_at |
When it passes the client-side max age. None unless it came from the keyring. |
Projects¶
client.projects() returns the projects the session's user can reach, as a list of Project:
| Field | Meaning |
|---|---|
id |
The number Odoo.sh gives the project. |
name |
The project's name on Odoo.sh, as in the address of its page. |
repository |
The GitHub repository the project builds, as owner/name. |
url |
The address of the project's page on Odoo.sh. |
Project overview¶
client.project_overview(project) returns what a project's page and its Settings page tell about
it, as a ProjectOverview. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
overview = client.project_overview("acme-shop")
print(overview.subscription, overview.odoo_version, overview.region, overview.access_level)
for counted in overview.stages:
print(counted.stage, counted.count)
if overview.hosting is not None:
print(overview.hosting.storage_used_bytes, overview.hosting.storage_quota_bytes, overview.hosting.workers)
| Field | Meaning |
|---|---|
id, name, repository |
As in Project. |
subscription |
A Subscription: VALID, TRIAL, NON_STANDARD, EXPIRED or UNKNOWN. |
subscription_name |
What Odoo.sh calls that state, such as valid. |
trial_days_left |
The days left of a trial given by a partnership code, or None. |
odoo_version |
The project's Odoo version, such as 19.0. |
region |
Where the project is hosted, in Odoo.sh's own words, such as Europe. |
dedicated |
Whether the project pays for a dedicated server. |
production_build |
A ProductionBuild, or None when there is none. |
access_level |
What the session's user is on the project: admin, tester or developer. |
hosting |
A ProjectHosting, or None when the user is not an admin of the project. |
stages |
A StageCount for production, staging and development, even at 0, then one for each stage the library does not know. |
branches |
A BranchSummary for each branch, in the order Odoo.sh answers them. |
| Model | Fields |
|---|---|
ProductionBuild |
id, branch_name and url, the address of the production database. |
ProjectHosting |
storage_used_bytes and storage_quota_bytes, workers of the production branch and staging_branches the subscription allows. |
StageCount |
stage, stage_name and count. |
BranchSummary |
branch, a Branch, and last_build, a TrackedBuild or None when it has none. |
- It asks Odoo.sh for the project's info, then the projects for its region, then its branches, as its page does, then for an admin its settings, as its Settings page does.
- Odoo.sh shows the Settings page to an admin of the project only, so
hostingisNonefor anyone else and the settings are not asked. - Sizes are in bytes. The storage used is what Odoo.sh accounts the project for.
- A subscription state the library does not know is
Subscription.UNKNOWN, not an error. - The project's access token, the GitHub token set for commit statuses, the subscription code, the subscription-management link that carries it and the enterprise code are in Odoo.sh's answers. They are dropped before anything is read, and none is in the model.
- A project the user cannot reach raises
NotFoundError. Branches or settings Odoo.sh refuses raisePermissionDeniedError.
Audit log¶
client.audit_log(project, timeout=...) yields the entries of a project's audit log, newest first,
as AuditEntry. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
for entry in client.audit_log("acme-shop", limit=10, timeout=60):
print(entry.logged_at, entry.author, entry.kind, entry.stage, entry.details)
| Field | Meaning |
|---|---|
logged_at |
When it was done, in UTC. |
author |
Who did it, as a GitHub login. Treat it as personal data. |
kind |
An AuditKind, such as OPEN_SHELL, DOWNLOAD_DATABASE or MANAGE_COLLABORATORS, or UNKNOWN. |
kind_name |
What Odoo.sh calls it, such as Open Shell, cut to 64 characters. |
stage |
The Stage of the branch it was done on, or None for an action on the project. |
details |
What Odoo.sh adds, often empty: addresses, logins, an SSH client's banner. Treat it as personal data and as untrusted text. |
succeeded |
Whether it succeeded. |
- Odoo.sh shows the log to an admin of the project only. The library makes the page's own test on
the project's info and raises
PermissionDeniedErrorfor anyone else, without asking for the log. - Odoo.sh has no paging: it sends the whole of the last 30 days in one answer. That request is sent
at the first read, and no entry past
limit, 25 by default, is turned into a model. - An answer over 16 MiB is not read and raises
OdoucheError. - The two requests, the project's info and the log, are bounded by
timeout: a request still to send at it, or one it cut short, raisesStreamTimeoutError, never a short log. - An action the library does not know is
AuditKind.UNKNOWN, with what Odoo.sh calls it inkind_name. Any other field not as seen raisesUpstreamChangedErrornaming it. author,detailsandkind_nameare as Odoo.sh sends them, control characters included: strip them before a terminal shows them.
Project settings¶
client.project_settings(project) returns a project's settings, as its Settings page shows them,
as ProjectSettings. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
settings = client.project_settings("acme-shop")
print(settings.session_lifetime, settings.public, settings.http_timeout_seconds)
for address in settings.ip_allow_list:
print(address)
| Field | Meaning |
|---|---|
name |
The project's name on Odoo.sh. |
odoo_domain_blocked |
Whether the production database is unreachable on its odoo.com domain. |
session_lifetime |
A SessionLifetime, how long a member's session lasts on the project: AUTO, or FOUR_HOURS to EIGHT_DAYS. |
public |
Whether the Builds page is open to visitors, who can then connect to the development builds. |
commit_statuses_suspended |
Whether Odoo.sh stopped sending commit statuses, as the check of their token failed. |
deploy_key_writable |
Whether the project's deploy key may push to its repository. |
submodules |
A Submodule for each private submodule. |
hosting |
A ProjectHosting, as in the overview. |
dedicated |
Whether the project pays for a dedicated server, the only one whose timeouts can be changed. |
http_timeout_seconds, cron_timeout_seconds |
How long an HTTP request and a scheduled action run before they are stopped. |
module_install to ai_agent |
The development defaults, as the fields of the same names in BranchSettings. |
ip_allow_list |
The entries allowed SSH, and PostgreSQL on a dedicated server, to production and staging, in the page's order: an IPv4Network or IPv6Network for an entry with a /, an IPv4Address or IPv6Address for any other, so each reads back as written. |
| Model | Fields |
|---|---|
Submodule |
id, url, fingerprint and public_key, the public half of the deploy key as one OpenSSH line, without the line break it may end with. |
SessionLifetime |
AUTO, which Odoo.sh sets as it sees fit up to 8 days, FOUR_HOURS, EIGHT_HOURS, ONE_DAY, TWO_DAYS, FOUR_DAYS and EIGHT_DAYS. |
- It asks Odoo.sh for the project's info, then its settings, and only reads. The settings request
is the one the overview sends for
hosting. - Odoo.sh shows the Settings page to an admin of the project only. The library makes the page's
own test on the project's info and raises
PermissionDeniedErrorfor anyone else, without asking for the settings. - A value the library does not know, in any of the enumerations, raises
UpstreamChangedErrornaming the field, as for a branch's settings. So does an allowed entry that is neither an address nor a network, or a deploy key that is not an OpenSSH public key line, neither of which the error quotes. - The GitHub token set for commit statuses, the subscription code and the subscription-management link that carries it are dropped before anything is read.
- A submodule's
urlis normalised before anything is read: it is the URL without its query, its fragment and its user information, which ends at the last@before the first/(after//in a URL that has one). A Unix user name that does not start as a GitHub or GitLab token does, such asgit, is kept in ansshURL or an scp-likeuser@host:path. urlis empty when a URL with//cannot be read safely: what is left before its path is not a host and a port, its scheme is not one, or a password came with an@in the path, which a password holding a/would also give.- A project the user cannot reach raises
NotFoundError. - The submodule URLs, modules and test tags come from what the project's admins typed: strip their control characters before a terminal shows them.
client.change_project_settingschanges them, as State-changing operations has it.
Members¶
client.members(project) returns the members of a project, with the role of each, as a list of
ProjectMember. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
members = client.members("acme-shop")
for member in sorted(members, key=lambda member: -member.role.rank):
print(member.login, member.role, "pending" if member.pending_login else "")
| Field | Meaning |
|---|---|
id |
The number of the membership, not of the person. |
login |
Their GitHub login. |
name |
What Odoo.sh calls them, the login in every member seen. |
role |
A MemberRole: DEVELOPER, TESTER or ADMIN. |
github_id |
Their GitHub user number, which stays when they rename their login. |
pending_login |
Whether they were invited and have not logged in to Odoo.sh yet. |
MemberRoleis declared lowest first, androle.rankis its place, 0 forDEVELOPER. Compare roles byrank: as aStrEnum,<compares its values as strings.- The members come in the order Odoo.sh answers them, which is by none of the fields.
- It asks Odoo.sh for the project's info, then its settings, and only reads: the members are part of the Settings page, with the same drops as Project settings.
- Odoo.sh shows that page to an admin of the project only. Anyone else gets
PermissionDeniedErrorbefore the settings are asked for. - A role the library does not know raises
UpstreamChangedErrornaming the field. - Odoo.sh gives no member's email, so there is no such field.
- A login and a name are another person's personal data, carried as given: strip their control characters before a terminal shows them.
- A project the user cannot reach raises
NotFoundError. client.add_memberandclient.set_member_rolechange them, as State-changing operations has it.
Branches¶
client.branches(project) returns the branches of a project, as a list of Branch. project is a
Project or a project's name.
| Field | Meaning |
|---|---|
id |
The number Odoo.sh gives the branch. |
name |
The git branch. |
stage |
A Stage: PRODUCTION, STAGING, DEVELOPMENT or UNKNOWN. |
stage_name |
What Odoo.sh calls that stage, such as dev. |
- The branches come in the order Odoo.sh answers them, which is not by name or by stage.
- A stage the library does not know is
Stage.UNKNOWN, not an error.stage_namesays which. - A project that is not among those the user can reach raises
NotFoundError, whether or not it exists. One that Odoo.sh lists but refuses the branches of raisesPermissionDeniedError. - Each call asks Odoo.sh twice: for the projects, then for the branches.
Backups¶
client.backups(project) returns the backups of a project, every branch's, newest first, as a list
of Backup. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
for backup in client.backups("acme-shop"):
print(backup.taken_at, backup.kind, backup.branch_name, backup.downloadable)
| Field | Meaning |
|---|---|
kind |
A BackupKind: MANUAL, DAILY, REMOTE or UNKNOWN. |
kind_name |
What Odoo.sh calls that kind. |
taken_at |
When it was taken, in UTC, to the second. It is what names the backup. |
build_name |
The name of the build it was taken from. |
branch_name, commit_hash |
The git branch and the full commit of that build. |
downloadable |
Whether Odoo.sh lets it be downloaded. |
size |
The bytes of its compressed SQL, or None: only a REMOTE backup has one. |
- A
REMOTEbackup is a daily one kept off-site, under the sametaken_atas theDAILYone while that is kept. Odoo.sh does not let it be downloaded as it is. - A backup has no number: the one Odoo.sh gives a
REMOTEbackup changes between two answers. - A project that is not among those the user can reach raises
NotFoundError, whether or not it exists. Each call asks Odoo.sh twice: for the projects, then for the backups.
Builds¶
client.builds(branch) returns the latest builds of a branch, newest first, as a list of Build.
branch is a Branch or a branch's number.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
for build in client.builds(branch, limit=2):
print(build.id, build.status, build.result, build.commit.hash)
latest = client.latest_build(branch)
| Field | Meaning |
|---|---|
id |
The number Odoo.sh gives the build. |
name |
The build's name on Odoo.sh. |
branch_id, branch_name |
The branch the build belongs to. |
commit |
A Commit: hash, message, author, timestamp and url. |
status |
A BuildStatus: PROGRESS, UPDATING, DONE, DROPPED, SKIPPED, KILLED or UNKNOWN. |
status_name |
What Odoo.sh calls that status. |
result |
A BuildResult: SUCCESS, FAILED, WARNING or UNKNOWN. None when Odoo.sh gives none. |
result_name |
What Odoo.sh calls that result. None with result. |
status_info |
What the build is doing, in Odoo.sh's own words, or None. |
started_at |
When a worker took the build. None while it waits for one. |
url |
The address of the build's database, or None. |
finished |
Whether the build has ended, whatever its result. |
finishedis true forDONE,DROPPED,SKIPPEDandKILLED. ADROPPEDbuild is one a newer build replaced.- A status or result the library does not know is
UNKNOWN, not an error, and the_namefield says which. An unknown status is not finished. - Timestamps are timezone-aware, in UTC.
limitdefaults to 4 and each call is one request. Odoo.sh may return fewer builds than asked for: it has only been seen to return up to four, and older builds are out of reach. Alimitunder 1 raisesValueError, and a branch, build or limit that is not an integerTypeError.client.latest_build(branch)returns the newest build, orNonefor a branch with none.client.build(branch, build_id)returns one build. Odoo.sh has no request for a build by its number, so it is looked for among the branch's latest and raisesNotFoundErrorwhen it is not there.- A branch the user cannot reach raises
NotFoundError. Odoo.sh gives no reason. - A commit's
authoris another person's name. Treat it as personal data.
client.watch_build(project, build, timeout=...) yields the build as it is now, then again at
each change, and ends once it has finished. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
build = client.latest_build(branch)
if build is None:
raise SystemExit("The branch has no build yet.")
try:
for build in client.watch_build("acme-shop", build, timeout=1800):
print(build.status, build.status_info)
except odouche.StreamTimeoutError:
print("Still running after half an hour.")
else:
print(build.result)
- A change is one of
status,resultorstatus_info. The last build yielded is the finished one, and a build that has already finished is yielded once, with no wait. - The watch stays on its build. A newer build on the branch ends it as
DROPPED. - With
pulse=2, the build is also yielded unchanged, every 2 seconds at least while nothing changes, so a caller that watches in a thread can close the iterator. - After
timeoutseconds it raisesStreamTimeoutError: the build is still running, which is not Odoo.sh being unavailable. A request of the watch waits no longer than what is left of them. - Changes come over a websocket to
www.odoo.sh. Odoo.sh is also asked for the build at the start, when the connection is opened again and after a minute with no news of the build, which is what detects a rejected session. - A connection that fails is opened again twice. Then
UpstreamUnavailableErroris raised. - Closing the iterator closes the connection.
- A build that is no longer among its branch's latest raises
NotFoundError.
History¶
client.history(branch, timeout=...) yields the events of a branch, newest first, as Tracking:
each push with its commits, each rebuild and each move between stages. branch is a Branch or a
branch's number. It reaches builds older than builds does.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
for event in client.history(branches["feature-invoicing"], limit=30, timeout=60):
print(event.created_at, event.kind, event.build and event.build.id, len(event.commits))
| Field | Meaning |
|---|---|
id |
The number Odoo.sh gives the event. |
kind |
A TrackingKind: PUSH, REBUILD, STAGE or UNKNOWN. |
kind_name |
What Odoo.sh calls that kind. |
created_at |
When it happened, in UTC. |
build |
A TrackedBuild: id, status, status_name, result and result_name, or None. |
commits |
The PushedCommits of a push, each with hash, message and url, and no author or date. |
pusher |
Who pushed, as Odoo.sh names them, or None. Treat it as personal data. |
source_stage, target_stage |
The Stages of a move, or None. A branch's creation has a target only. |
- Odoo.sh answers twenty events a request. The next twenty are asked for only when the iterator is
read past the last ones, and none once
limitevents, 20 by default, are yielded. - That the next twenty are at an offset of twenty is inferred, not seen. An event read again,
because a newer one pushed it down, is skipped. A page with nothing older raises
UpstreamChangedErrorrather than looping. - A page still to be asked for after
timeoutseconds raisesStreamTimeoutError. A request waits no longer than what is left of them. - The build is as it is now, with no commit, name or address:
client.buildhas the rest of a build that is still among the branch's latest.
Branch settings¶
client.branch_settings(branch) returns a branch's settings, as its Settings tab shows them, as
BranchSettings. branch is a Branch or a branch's number.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
settings = client.branch_settings(branches["feature-invoicing"])
print(settings.push_behavior, settings.machine)
| Field | Meaning |
|---|---|
push_behavior |
A PushBehavior, what a new commit does: NOTHING, NEW_BUILD or UPDATE. |
project_defaults |
Whether the project's development defaults apply instead of the six fields below. |
module_install |
A ModuleInstall, the modules a new build installs: REPOSITORY, ALL or LISTED. |
modules |
The modules stored for LISTED, whatever module_install is. They apply only to LISTED. |
tests |
A BuildTests, the tests a new build runs: OFF, MODULES (the installed modules') or TAGS. |
test_tags |
The Odoo test tags stored for TAGS, whatever tests is, or None. They apply only to TAGS. |
demo_data |
Whether a new build loads demonstration data. |
ai_agent |
An AiAgent, the agent the AI tab runs: CLAUDE or OPENCODE. |
odoo_version |
The Odoo version, such as 19.0, or None for the project's. |
odoo_revision_id |
The id Odoo.sh gives the pinned weekly Odoo revision, or None for the latest. Its name is not given. |
machine, recommended_machine |
The operating system builds run on, and the one Odoo.sh recommends, such as ubuntu-24.04. |
next_machine |
The operating system the next commit's build moves to, or None. |
domains |
The custom domains. |
dns_target |
The host a custom domain's CNAME record points to. |
- It is one request, and only reads.
- A value the library does not know, in any of the four enumerations, raises
UpstreamChangedErrornaming the field, unlike aStagethat becomesUNKNOWN: a setting is never passed through unchecked. - The new build options,
project_defaultstoai_agent, apply to a development branch only. Whileproject_defaultsis true the project's development defaults apply instead, which Project settings reads. - Odoo.sh has no settings request for a build, as
Client.buildsays. client.change_branch_settingschanges them, as State-changing operations has it.
Build revision¶
client.build_revision(project, build) returns what a build of a project runs, as
BuildRevision: its head commit, its Odoo version, and the Odoo revision its branch has selected,
with the commit of each of Odoo's own repositories. project is a Project or a project's name.
import odouche
with odouche.Client() as client:
build = client.build(51044, 88212)
revision = client.build_revision("acme-shop", build)
print(revision.commit.hash)
if revision.branch_odoo_revision is not None:
for ref in revision.branch_odoo_revision.refs:
print(ref.repository, ref.commit_hash)
BuildRevision field |
Meaning |
|---|---|
build_id, build_name, branch_name |
The build's number and name, and its git branch. |
commit |
The head commit of the project's repository, as a Commit, with its full hash. |
odoo_version |
The Odoo version the build was made with, such as 19.0. |
branch_odoo_revision |
The OdooRevision the branch has selected now, or None. |
OdooRevision field |
Meaning |
|---|---|
id |
The number Odoo.sh gives the revision, as BranchSettings.odoo_revision_id holds it when pinned. |
version |
The Odoo version, such as 19.0. |
pinned |
Whether the branch pins this revision. Otherwise it is the latest of its version, and moves on. |
refs |
An OdooRef for each repository, in the order Odoo.sh gives them. |
OdooRef field |
Meaning |
|---|---|
repository |
What Odoo.sh calls the repository, such as enterprise. |
commit_hash |
The commit's full hash. |
url |
The repository's address. |
- It is two requests, and only reads. A branch with no Odoo version of its own follows the project's, which is a third request.
- Odoo.sh ties no Odoo revision to a build:
branch_odoo_revisionis the one the branch has selected now, which the build may not run. branch_odoo_revisionisNonewhen Odoo.sh gives none.- Odoo.sh gives no commit for a submodule of the project's repository, so nothing in the model says whether the repository has submodules.
- An answer not in the shape seen raises
UpstreamChangedErrornaming the field.
Logs¶
client.logs(project, build) returns the logs a build has, as a list of Log. project is a
Project or a project's name, and build a Build.
| Field | Meaning |
|---|---|
kind |
A LogKind: INSTALL, PIP, ODOO, UPDATE, NEUTRALIZE, UPGRADE or UNKNOWN. |
name |
What Odoo.sh calls the log. |
modified_at |
When it was last written to, in UTC. |
size |
Its size in Odoo.sh's own words, such as 156 KB. |
client.read_log(project, build, kind) yields the lines of one log, and
client.follow_log(project, build, kind, timeout=...) the lines written from now on. kind is a
LogKind or a log's name.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
build = client.latest_build(branch)
if build is None:
raise SystemExit("The branch has no build yet.")
for log in client.logs("acme-shop", build):
print(log.name, log.size)
for line in client.read_log("acme-shop", build, odouche.LogKind.INSTALL, tail=20):
print(repr(line.text))
try:
for line in client.follow_log("acme-shop", build, odouche.LogKind.ODOO, timeout=600):
print(repr(line.text))
except odouche.StreamTimeoutError:
print("Followed for ten minutes.")
Each line is a LogLine:
| Field | Meaning |
|---|---|
text |
The line without its newline. |
offset |
The byte just past the line. |
truncated |
Whether the line was cut. |
Log content is untrusted
A line is whatever a process printed, unchanged: it can hold terminal escape sequences and secrets of the instance. Neutralise it before showing it.
- A build has only some of the logs, and none while it waits for a worker. A log it does not have
raises
NotFoundError. tail=Nyields the last N lines, out of the log's last mebibyte.- Closing the iterator of a read closes the connection.
- A line longer than 64 KiB is cut to that and marked
truncated. Bytes that are not UTF-8 are replaced. follow_logstarts after the lasttaillines, none by default, or atoffset: pass theoffsetof the last line read to carry on from it.- A follow asks Odoo.sh every second and ends when the iterator is closed. After
timeoutseconds it raisesStreamTimeoutError.timeout=math.infsets no limit. - A request that fails is sent again twice, from where the last one stopped, so no line is lost
or repeated. Then
UpstreamUnavailableErroris raised. - Each call asks Odoo.sh for the build's worker and the project's access token before the log. Security says what happens to the token.
Caught mails¶
A development or a staging build sends no mail: Odoo.sh catches each one on the build's worker.
client.mails(project, branch, build) lists them as Mails, newest first, and
client.mail(project, branch, build, mail_id) returns one as a MailContent, with its text.
build is a build of branch.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
build = client.latest_build(branch)
if build is None:
raise SystemExit("The branch has no build yet.")
caught = client.mails("acme-shop", branch, build, limit=10)
for mail in caught:
print(mail.id, repr(mail.subject))
if caught:
content = client.mail("acme-shop", branch, build, caught[0].id)
print(repr(content.body))
for attachment in content.attachments:
print(repr(attachment.name), attachment.size)
Mail field |
Meaning |
|---|---|
id |
The worker's name for the mail, which mail takes. |
date |
When the mail is dated, in UTC, or None when date_text is not a date. |
date_text |
The date as the worker gives it. |
sender |
The From header, as written. |
recipients |
The To header, as written. |
subject |
The Subject header, as written. |
MailContent field |
Meaning |
|---|---|
mail |
The Mail. |
cc |
The Cc header, as written. |
body |
The plain text part, or the HTML part turned into text. |
attachments |
Each attached file's name and size in bytes. Its content is not read. |
truncated |
Whether the body was cut, or the mail was too large to read. |
Mail content is untrusted
Every field but id was written by the build's code or its data: a subject or a body can
hold terminal escape sequences, links and instructions. Neutralise it before showing it, and
never follow it.
- Only a development or a staging branch's builds have mails. Any other stage raises
NotFoundErrorbefore a request, and a build of another branch raisesValueError. - The worker keeps the latest 1000 mails of a build. A build waiting for a worker has none.
- An HTML body is turned into text: scripts, styles and images are dropped, a link keeps its address after its text, and nothing is fetched or rendered. Only its first 2097152 characters are read.
- A body is cut at 1 MiB as UTF-8, a header at 65536 characters, and the parts read at 1000,
counting every MIME part, containers included. A forwarded mail is one attachment, whose parts
are not read. A mail over 16 MiB, attachments
included, is not read, nor is one whose source cannot be parsed: its
bodyandattachmentsare empty. Each setstruncated. - A worker's list of mails over 16 MiB is not read either, and raises
OdoucheError. - Half of a surrogate pair in a header, which JSON can hold, is replaced with
?. A mail whoseidholds one is listed, andmailraisesNotFoundErrorfor it: its id cannot be sent back. - Each call asks Odoo.sh for the build's worker and the project's access token, then the worker
for the list;
mailasks it for that mail too. Security says what happens to the token.
A shell on a build¶
client.ssh_target(build) returns the SshTarget of a build: the user and the host that
ssh reaches it with. Odoo.sh is not asked, and the library opens no connection and reads no key.
import odouche
with odouche.Client() as client:
build = client.build(51044, 88212)
target = client.ssh_target(build)
print("ssh", "-l", target.user, target.host)
- Both values are checked to be safe as arguments of
ssh: one that is not raisesUpstreamChangedError. - A build with no address raises
NotFoundError.
A build host accepts SSH only from an address Odoo.sh allows, and no request of Odoo.sh tells
whether this machine's is. client.allow_ip(branch) allows it: see
State-changing operations.
A build's panels¶
client.panel_url(project, branch, build, panel) returns the address of a build's monitor, shell
or editor, for a browser to open. panel is a Panel (MONITOR, SHELL or EDITOR) or its
name, and build a build of branch.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
build = client.latest_build(branch)
if build is None:
raise SystemExit("The branch has no build yet.")
try:
print(client.panel_url("acme-shop", branch, build, odouche.Panel.SHELL))
except odouche.NotFoundError as error:
print(error)
- Odoo.sh is not asked: the URL is built from the build and its branch, and only reads.
- A build has panels once it is
DONE, as on the page. Any other raisesNotFoundError, which says when the build is still waiting for a worker. - The shell and the editor are on the build's own host. The monitor is the branch's, on
www.odoo.sh, and shows its latest build: only a staging or a production branch has one. - No URL carries a token or the session. The browser that opens it signs in to Odoo.sh on its own.
- A build address that is not a bare host under
odoo.comraisesUpstreamChangedError.
State-changing operations¶
Every other call of the client only reads. These are the calls that change something on Odoo.sh:
| Call | What it changes |
|---|---|
client.rebuild(branch) |
Starts a new build of the branch, which replaces its latest one. |
client.allow_ip(branch) |
Lets this machine's address connect with ssh for one hour, to the branch's builds and, as seen, the project's others. |
client.create_backup(project, branch) |
Takes a manual backup of the branch's latest build, which Odoo.sh keeps for three days. |
client.prepare_download(project, backup) |
Has Odoo.sh prepare the backup's file, which it keeps for 2 hours. |
client.change_branch_settings(branch, change) |
Sets the settings a SettingsChange gives on the branch. |
client.change_project_settings(project, change) |
Sets the settings a ProjectSettingsChange gives on the project, the IP allow list by entry. |
client.move_branch(branch, to) |
Moves the branch between development and staging. |
client.add_member(project, login, role) |
Adds a GitHub user to the project's members with the role given. |
client.set_member_role(project, member, role) |
Gives a member of the project another role. |
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
build = client.rebuild(branch)
for build in client.watch_build("acme-shop", build, timeout=1800):
print(build.status, build.status_info)
odouche.Client(read_only=True)refuses them: the call raisesReadOnlyErrorand nothing is sent, not even the reads the call starts with.client.read_onlytells which a client is.- The request is sent once and never repeated. When it left and Odoo.sh did not confirm it, or
the new build cannot be found, the call raises
OutcomeUnknownError: look at the branch before calling again, since a second call can start a second build. rebuildtakes aBranchor a branch's number and returns the newBuild. It asks Odoo.sh three times: for the branch's latest build, for the rebuild, then for the new build.- Only a development or a staging branch is rebuilt. Any other stage raises
StageRefusedErrorbefore the rebuild is sent, and before any request when aBranchin that stage is passed. A rebuild has only been observed on a development branch. client.check_rebuild(branch)raises the sameStageRefusedErrorfor aBranchand asks nothing, on a read-only client too: call it before asking the user.allow_iptakes aBranchor a branch's number and returns the address Odoo.sh allowed, anipaddress.IPv4AddressorIPv6Address. It sends no address: Odoo.sh takes the one the request comes from, which is a proxy's when one is in the environment. Odoo.sh says the rule lasts one hour and takes up to five minutes to apply; one was seen to take longer. A user whose access does not reach the branch's stage is expected to getPermissionDeniedError.- The library asks for no confirmation. That is the caller's to do.
create_backuptakes the project and the branch, each as a model or by its name or number, and an optionalcomment, and returns aBackupRequest, which names thebuildbacked up. Odoo.sh answers nothing about the backup, soclient.wait_for_backup(project, request, timeout=...)asks for the project's backups every five seconds and yieldsNoneuntil the new manual backup of that build is listed and Odoo.sh has finished it, then thatBackup. It raisesStreamTimeoutErrorat the timeout. A backup has been seen listed 58 seconds after the request and finished 19 seconds later; Odoo.sh refuses a file of it until then.- Only a staging or a production branch is backed up, checked as for a rebuild, with
client.check_backup(branch). A backup has only been observed on a staging branch.
import odouche
with odouche.Client() as client:
request = client.create_backup("acme-shop", 51044, comment="before the upgrade")
for backup in client.wait_for_backup("acme-shop", request, timeout=600):
if backup is not None:
print(backup.taken_at)
change_branch_settingstakes aBranchor a branch's number and aSettingsChange, whose fields are those ofBranchSettingsfrompush_behaviortoai_agent, and returns aSettingsOutcome: the settingsbeforeandafterthe change. A field leftNoneis not sent. Of the others, only those that differ from the branch's are sent, in one request, as the page sends one section of the Settings tab, and the rest keep their value: that this holds for every field is inferred, not seen (Upstream reference). Nothing differing, it sends nothing. It asks Odoo.sh four times: for the branch's stage, its settings, the change, then its settings again. When a setting sent does not read back as sent, it raisesOutcomeUnknownErrornaming it; sending the same change again does no harm. A setting not sent that Odoo.sh changed along, as it may one that depends on another, is in the outcome'smoved.SettingsChangeraisesValueErrorwhen it gives nothing, for a module name of anything but ASCII letters, digits and underscores, and for test tags of other characters thanA-Z a-z 0-9 _/:.,*+-[]; an emptytest_tagsclears them.- What a new commit does is not changed on a production branch, and the new build options only on
a development branch: any other raises
StageRefusedErrorbefore the change is sent. An option the Settings tab disables or hides, given the settings after the change, raisesSettingsConflictError, aValueError: one of the branch's own whileproject_defaultsstays true,modulesbut forLISTED, tests withALL, ortest_tagsbut forTAGS. client.check_settings_change(branch, current, change)returns the part of the change that differs fromcurrent, orNone, and raises as the change would, asking nothing: call it before asking the user.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-invoicing"]
change = odouche.SettingsChange(push_behavior=odouche.PushBehavior.UPDATE)
if client.check_settings_change(branch, client.branch_settings(branch), change) is not None:
outcome = client.change_branch_settings(branch, change)
print(outcome.after.push_behavior, outcome.moved)
change_project_settingstakes aProjector a project's name and aProjectSettingsChange, and returns aSettingsOutcomeofProjectSettings. It works aschange_branch_settingsdoes, for an admin of the project: anyone else getsPermissionDeniedErrorbefore the settings are asked for.movedcovers every setting but the name, the hosting figures and the submodules, those the change cannot send included, such asdeploy_key_writable. It asks Odoo.sh four times, twice when nothing differs: for the project's info, its settings, the change, then its settings again.- Its fields are the session lifetime, public access, the two timeouts, the development defaults,
named as in
ProjectSettings, and the allow list by entry:allow_ipsaddsIPv4Addresses anddisallow_ipsremoves entries asip_allow_listreads them. The list is sent whole, as the page sends it: each line kept as written, those removed left out, the addresses added at the end. The lines come from a read made in the same call, so an edit made elsewhere in between is overwritten, as it is by the page. An address already allowed, or an entry not listed, is left out of what is sent. Both timeouts are sent when either is given, the other with its value as read, as the page sends its workers section.ACCESSnames the fields that change who can reach the project, andaccess()those a change gives. ProjectSettingsChangeraisesValueErrorasSettingsChangedoes, and for a timeout of 0 or less, an empty or repeated entry, an entry both to allow and to remove, or an address to allow that is unspecified, loopback, multicast, link-local or reserved. An address to allow that is not anIPv4AddressraisesTypeError.SettingsConflictErroris raised before the change for a timeout on a project with no dedicated server, one that is not a whole number of the page's unit or out of its bounds, a development default the page hides as a branch's tab does, or an allow list over ten entries. A change that only removes entries is never refused.client.check_project_settings_change(current, change)checks all of it but a timeout's unit and bounds, which the settings do not hold.
import ipaddress
import odouche
with odouche.Client() as client:
change = odouche.ProjectSettingsChange(
ai_agent=odouche.AiAgent.OPENCODE, allow_ips=(ipaddress.IPv4Address("203.0.113.7"),)
)
current = client.project_settings("acme-shop")
narrowed = client.check_project_settings_change(current, change)
if narrowed is not None:
print("access:", narrowed.access())
outcome = client.change_project_settings("acme-shop", narrowed)
print(outcome.after.ip_allow_list, outcome.moved)
move_branchtakes aBranchor a branch's number and theStageto move it to, and returns theBranchread back in that stage. A move to staging starts a build on a copy of production's data, whichclient.latest_build(moved)finds; a move to development drops the branch's staging builds, which are not backed up. It asks Odoo.sh three times: for the branch's stage, the move, then the branch again. When the branch does not read back in the new stage, it raisesOutcomeUnknownError.- Only a move between development and staging is sent. A production branch, a move to production, a
stage the library does not know and a branch already in
toraiseStageRefusedErrorbefore the move, and before any request when theBranchpassed already shows it. The stage that decides is the one read in the same call, so aBranchread earlier can refuse a move but never allow one.client.check_move(branch, to)raises the same refusals for aBranchand asks nothing, on a read-only client too.
import odouche
with odouche.Client() as client:
branches = {branch.name: branch for branch in client.branches("acme-shop")}
branch = branches["feature-reports"]
client.check_move(branch, odouche.Stage.STAGING)
moved = client.move_branch(branch, odouche.Stage.STAGING)
print(moved.stage, client.latest_build(moved))
add_membertakes aProjector a project's name, a GitHub login and aMemberRole,DEVELOPERunless given, and returns theProjectMemberread back. Odoo.sh sends them no invitation, as the page sends none, and push access to the repository is given on GitHub. A login that breaks GitHub's rule for a new account (1 to 39 ASCII letters, digits and single inner hyphens) raisesValueErrorbefore any request: an older login that breaks it is added in the page. It asks Odoo.sh five times: for the project's info, the members, a search of GitHub for the login, the addition, then the members again.- A user already a member, by login in any case or by GitHub number under a login since renamed,
raises
MemberRefusedErrorbefore the addition. The search must find the login exactly, as the page's own Enter does: otherwiseNotFoundError. The search needs Odoo.sh's grant on GitHub to cover private repositories: when it does not,PermissionDeniedErrorsays to search a user once in the Collaborators item of the project's Settings page, which asks GitHub for it. set_member_roletakes the project, aProjectMemberor a login in any case, and aMemberRole, and returns the member read back. It asks Odoo.sh four times, twice when the member already has the role, when nothing is sent: for the project's info, the members, the change, then the members again. A member not listed raisesNotFoundError. Lowering an admin when no other admin who has logged in to Odoo.sh remains raisesMemberRefusedError: an invitee who never logs in leaves nobody to administer the project. An admin who lowers their own role can no longer read the members, so their role is read back from the project's info.- Both read the members in the same call, for an admin of the project only: anyone else gets
PermissionDeniedErrorbefore the members are asked for. When the member read back is missing or has another role, they raiseOutcomeUnknownError. client.check_add_member(login, role, current)andclient.check_member_role(current, member, role)raise the same refusals, given the memberscurrent, and ask nothing, on a read-only client too.check_member_rolereturns the member as listed incurrent: when theirroleis already the one asked,set_member_rolesends nothing.
import odouche
with odouche.Client() as client:
current = client.members("acme-shop")
client.check_add_member("octo-cat", odouche.MemberRole.TESTER, current)
added = client.add_member("acme-shop", "octo-cat", odouche.MemberRole.TESTER)
found = client.check_member_role(current, "jane-doe", odouche.MemberRole.DEVELOPER)
if found.role is not odouche.MemberRole.DEVELOPER:
changed = client.set_member_role("acme-shop", "jane-doe", odouche.MemberRole.DEVELOPER)
print(changed.login, changed.role)
print(added.login, added.role)
prepare_downloadtakes the project and aBackupthat isdownloadable, andneutralized=Falsefor the exact database orfilestore=Falseto leave the filestore out. It returns aPreparedDownload, whoselinkis the page's link to the file. It is sent on the build the backup was taken from, and raisesNotFoundErroronce that build is no longer among its branch's latest.client.wait_for_download(project, prepared, timeout=...)asks for the project's notifications every five seconds and yieldsNoneuntil Odoo.sh says the file is ready, which took 30 seconds for a small database. Preparing twice does no harm.client.find_download(project, backup)takes the same choices and returns thePreparedDownloadof a file Odoo.sh already holds, orNone. It only reads: it looks for the notification of the file, then opens the file once to tell it is still there. Odoo.sh says it keeps a file for 2 hours.client.download(prepared)is a context manager that gives aBackupFile: itssize, when Odoo.sh says it, and itschunksas they arrive. Odoo.sh hands over a token for the file, which is sent to the build's worker alone and kept nowhere: the token grants the file to whoever holds it. Where the file is written, and who may read it, is the caller's to decide.
import os
import odouche
with odouche.Client() as client:
backup = next(found for found in client.backups("acme-shop") if found.downloadable)
prepared = client.find_download("acme-shop", backup)
if prepared is None:
prepared = client.prepare_download("acme-shop", backup)
for _ in client.wait_for_download("acme-shop", prepared, timeout=600):
pass
private = os.open("backup.zip", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with client.download(prepared) as file, open(private, "wb") as out:
for chunk in file.chunks:
out.write(chunk)
Errors¶
Everything the library raises is an OdoucheError, so one except catches any failure and no
HTTP client exception has to be imported.
import odouche
try:
with odouche.Client() as client:
names = [project.name for project in client.projects()]
except (odouche.NoSessionError, odouche.SessionExpiredError):
raise SystemExit("Log in to Odoo.sh first.") from None
except odouche.OdoucheError as error:
raise SystemExit(str(error)) from None
print(names)
| Error | Meaning |
|---|---|
NoSessionError |
There is no session. Log in. |
SessionExpiredError |
Odoo.sh rejected the session, or it passed its max age. Log in again. |
NotFoundError |
The project, branch, build or log is not one the session's user can reach. |
PermissionDeniedError |
The session is not allowed to do this. |
UpstreamChangedError |
Odoo.sh answered in a shape the library does not read. Please report it. |
UpstreamUnavailableError |
Odoo.sh could not be reached, or answered with a server error. |
ReadOnlyError |
A read-only client was asked to change state. Nothing was sent. |
StageRefusedError |
The branch is in a stage, or is asked into one, the library does not change. Nothing was sent. |
MemberRefusedError |
A change of the members the library does not send: someone already a member added, or the last admin lowered. Nothing was sent. |
OutcomeUnknownError |
A state-changing request was sent and Odoo.sh did not confirm it. Look before trying again. |
StreamTimeoutError |
A build was still being watched, or a log followed, at its timeout. |
KeyringUnavailableError |
No accepted keyring backend is available to store the session. |
LoginError |
The login ended without a session, or the pasted one was refused. |
LoginTimeoutError |
Nobody completed the browser login before its timeout. |
An error carries operation, status and a message. It never carries a session value, request
headers or a response body.
Stability¶
- The public API is what
odoucheexports: the names inodouche.__all__, which the API reference lists one by one. A module or a name with a leading underscore,odouche._upstreamincluded, is not, and changes without notice. - Below 1.0, a minor release can break the public API and a patch release does not. The changelog marks each breaking change.
- Odoo.sh can break the library in any release, since it has no public API. A caller sees
that as
UpstreamChangedError, whoseoperationandfieldname the request and what could not be read in its answer. No retry helps, and the input is not at fault. - Report one on the issue tracker with the error's message, which holds no session value. Leave out the answer itself: it holds your projects' data.