ops.hookcmds

Low-level access to the Juju hook commands.

Charm authors should use the ops.Model (via self.model) rather than directly running the hook commands, where possible. This module is primarily provided to help with developing charming alternatives to the Ops framework.

Note: hookcmds is not covered by the semver policy that applies to the rest of Ops. We will do our best to avoid breaking changes, but we reserve the right to make breaking changes within this package if necessary, within the Ops 3.x series.

All methods are 1:1 mapping to Juju hook commands. This is a low-level API, available for charm use, but expected to be used via higher-level wrappers.

See Juju | Hook commands and Juju | Hook command list for a list of all Juju hook commands.

class ops.hookcmds.Address(*, hostname: str, value: str, cidr: str)[source]

Bases: object

A Juju space address, found in BindAddress objects.

cidr: str
hostname: str
value: str
class ops.hookcmds.AppStatus(
*,
status: str = '',
message: str = '',
status_data: dict[str, Any],
units: dict[str, UnitStatus],
)[source]

Bases: object

The status of a Juju application.

message: str = ''
status: str = ''
status_data: dict[str, Any]
units: dict[str, UnitStatus]
class ops.hookcmds.BindAddress(
*,
mac_address: str,
interface_name: str,
addresses: list[~ops.hookcmds._types.Address] = <factory>,
)[source]

Bases: object

A Juju space bind address, found in Network objects.

addresses: list[Address]
interface_name: str
mac_address: str
class ops.hookcmds.CloudCredential(
*,
auth_type: str,
attributes: dict[str,
str] = <factory>,
redacted: list[str] = <factory>,
)[source]

Bases: object

Credentials for cloud.

Used as the type of attribute credential in CloudSpec.

attributes: dict[str, str]

A dictionary containing cloud credentials.

For example, for AWS, it contains access-key and secret-key; for Azure, application-id, application-password and subscription-id can be found here.

auth_type: str

Authentication type.

redacted: list[str]

A list of redacted secrets.

class ops.hookcmds.CloudSpec(
*,
type: str,
name: str,
region: str | None = None,
endpoint: str | None = None,
identity_endpoint: str | None = None,
storage_endpoint: str | None = None,
credential: ~ops.hookcmds._types.CloudCredential | None = None,
ca_certificates: list[str] = <factory>,
skip_tls_verify: bool = False,
is_controller_cloud: bool = False,
)[source]

Bases: object

Cloud specification information (metadata) including credentials.

ca_certificates: list[str]

A list of CA certificates.

credential: CloudCredential | None = None

Cloud credentials with key-value attributes.

endpoint: str | None = None

Endpoint of the cloud.

identity_endpoint: str | None = None

Identity endpoint of the cloud.

is_controller_cloud: bool = False

If this is the cloud used by the controller, defaults to False.

name: str

Juju cloud name.

region: str | None = None

Region of the cloud.

skip_tls_verify: bool = False

Whether to skip TLS verification.

storage_endpoint: str | None = None

Storage endpoint of the cloud.

type: str

Type of the cloud.

exception ops.hookcmds.Error(*, returncode: int, cmd: list[str], stdout: str = '', stderr: str = '')[source]

Bases: Exception

Raised when a hook command exits with a non-zero code.

cmd: list[str]

The full command that was run.

returncode: int

Exit status of the child process.

stderr: str = ''

Stderr output of the child process.

stdout: str = ''

Stdout output of the child process.

class ops.hookcmds.Goal(*, status: str, since: datetime)[source]

Bases: object

A goal status and when it was last updated, found in GoalState objects.

since: datetime
status: str
class ops.hookcmds.GoalState(
*,
units: dict[str, Goal],
relations: dict[str, dict[str, Goal]],
)[source]

Bases: object

The units and relations that the model should have, and the status of achieving that.

relations: dict[str, dict[str, Goal]]
units: dict[str, Goal]
class ops.hookcmds.Network(
*,
bind_addresses: Sequence[BindAddress],
egress_subnets: Sequence[str],
ingress_addresses: Sequence[str],
)[source]

Bases: object

A Juju space.

bind_addresses: Sequence[BindAddress]
egress_subnets: Sequence[str]
ingress_addresses: Sequence[str]
class ops.hookcmds.Port(
protocol: Literal['tcp', 'udp', 'icmp'] | None = 'tcp',
port: int | None = None,
to_port: int | None = None,
endpoints: list[str] | None = None,
)[source]

Bases: object

A port that Juju has opened for the charm.

endpoints: list[str] | None = None

The endpoints this port applies to, ['*'] if all endpoints, or None if unknown.

port: int | None = None

The port number. Will be None if protocol is 'icmp'.

protocol: Literal['tcp', 'udp', 'icmp'] | None = 'tcp'

The IP protocol.

to_port: int | None = None

The final port number if this is a range of ports.

class ops.hookcmds.RelationModel(*, uuid: str)[source]

Bases: object

Details of the model on the remote side of the relation.

uuid: str
class ops.hookcmds.SecretInfo(
*,
revision: int,
id: str = '',
label: str = '',
description: str = '',
expiry: datetime | None = None,
rotation: Literal['never', 'hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | None = None,
rotates: datetime | None = None,
)[source]

Bases: object

Metadata for Juju secrets.

description: str = ''
expiry: datetime | None = None
id: str = ''
label: str = ''
revision: int
rotates: datetime | None = None
rotation: Literal['never', 'hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | None = None
class ops.hookcmds.Storage(*, kind: str, location: Path)[source]

Bases: object

Metadata for Juju storage.

kind: str
location: Path
class ops.hookcmds.UnitStatus(
*,
status: str = '',
message: str = '',
status_data: dict[str, Any],
)[source]

Bases: object

The status of a Juju unit.

message: str = ''
status: str = ''
status_data: dict[str, Any]
ops.hookcmds.action_fail(message: str | None = None)[source]

Set action fail status with message.

For more details, see: Juju | Hook commands | action-fail

Parameters:

message – the failure error message. Juju will provide a default message if one is not provided.

ops.hookcmds.action_get(key: str | None = None) → dict[str, Any] | str[source]

Get action parameters.

action_get returns the value of the parameter at the given key. If a dotted key (for example foo.bar) is passed, action_get will recurse into the parameter map as needed.

For more details, see: Juju | Hook commands | action-get

Parameters:

key – The key of the action parameter to retrieve. If not provided, all parameters will be returned.

ops.hookcmds.action_log(message: str)[source]

Record a progress message for the current action.

For more details, see: Juju | Hook commands | action-log

Parameters:

message – The progress message to provide to the Juju user.

ops.hookcmds.action_set(results: Mapping[str, Any])[source]

Set action results.

For more details, see: Juju | Hook commands | action-set

Parameters:

results – The results map of the action, provided to the Juju user.

ops.hookcmds.app_version_set(version: str)[source]

Specify which version of the application is deployed.

For more details, see: Juju | Hook commands | application-version-set

Parameters:

version – the version of the application software the unit is running. This could be a package version number or some other useful identifier, such as a Git hash, that indicates the version of the deployed software. It shouldn’t be confused with the charm revision.

ops.hookcmds.close_port(
protocol: str | None = None,
port: int | None = None,
*,
to_port: int | None = None,
endpoints: str | Iterable[str] | None = None,
)[source]

Register a request to close a port or port range.

For more details, see: Juju | Hook commands | close-port

ops.hookcmds.config_get(
key: str | None = None,
) → Mapping[str, bool | int | float | str] | bool | int | float | str[source]

Retrieve application configuration.

Note that ‘secret’ type options are returned as string secret IDs.

If called without arguments, returns a dictionary containing all config settings that are either explicitly set, or which have a non-nil default value. If called with a key, it returns the value of that config option. Missing config keys are reported as nulls, and do not return an error.

For more details, see: Juju | Hook commands | config-get

Parameters:

key – The configuration option to retrieve.

ops.hookcmds.credential_get() → CloudSpec[source]

Access cloud credentials.

For more details, see: Juju | Hook commands | credential-get

ops.hookcmds.goal_state() → GoalState[source]

Print the status of the charm’s peers and related units.

For more details, see: Juju | Hook commands | goal-state

ops.hookcmds.is_leader() → bool[source]

Obtain the current leadership status for the unit the charm code is executing on.

The value is not cached. It is accurate for 30s from the time the method is successfully called.

For more details, see: Juju | Hook commands | is-leader

ops.hookcmds.juju_log(
message: str,
*,
level: Literal['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR'] = 'INFO',
)[source]

Write a message to the juju log.

For more details, see: Juju | Hook commands | juju-log

Parameters:

  • message – The message to log.

  • level – Send the message at the given level.

ops.hookcmds.juju_reboot(*, now: bool = False)[source]

Reboot the host machine.

For more details, see: Juju | Hook commands | juju-reboot

Parameters:

now – Reboot immediately, killing the invoking process.

ops.hookcmds.network_get(
binding_name: str,
*,
relation_id: int | None = None,
) → Network[source]

Get network config.

For more details, see: Juju | Hook commands | network-get

Parameters:

  • binding_name – A name of a binding (relation name or extra-binding name).

  • relation_id – An optional relation id to get network info for.

ops.hookcmds.open_port(
protocol: str | None = None,
port: int | None = None,
*,
to_port: int | None = None,
endpoints: str | Iterable[str] | None = None,
)[source]

Register a request to open a port or port range.

For more details, see: Juju | Hook commands | open-port

Parameters:

  • protocol – Open the port(s) for the specified protocol.

  • port – If to_port is not specified, open only this port.

  • to_port – Open a range of ports from port to to_port.

  • endpoints – If not provided, ports will be opened for all defined application endpoints. To constrain the open request to specific endpoints, provide one or more endpoint names.

ops.hookcmds.opened_ports(*, endpoints: bool = False) → list[Port][source]

List all ports or port ranges opened by the unit.

For more details, see: Juju | Hook commands | opened-ports

Parameters:

endpoints – If True, each entry in the port list will be augmented with a list of endpoints that the port applies to. If a port applies to all endpoints, this will be indicated by an endpoint of *.

ops.hookcmds.relation_get(
id: int | None = None,
*,
key: str | None = None,
unit: str | None = None,
app: bool = False,
) → dict[str, str] | str[source]

Get relation settings.

Note that id can only be None if the current hook is a relation event, in which case Juju will use the ID of the relation that triggered the event.

For more details, see: Juju | Hook commands | relation-get

Parameters:

  • app – Get the relation data for the overall application, not just a unit

  • id – The ID of the relation to get data for, or None to get data for the relation that triggered the current hook.

  • key – The specific key to get data for, or None to get all data.

  • unit – The unit to get data for, or None to get data for all units.

ops.hookcmds.relation_ids(name: str) → list[str][source]

List all relation IDs for the given endpoint.

For more details, see: Juju | Hook commands | relation-ids

Parameters:

name – the endpoint name.

ops.hookcmds.relation_list(id: int | None = None, *, app: bool = False) → list[str][source]

List relation units.

Note that id can only be None if the current hook is a relation event, in which case Juju will use the ID of the relation that triggered the event.

For more details, see: Juju | Hook commands | relation-list

Parameters:

  • id – The ID of the relation to list units for, or None to list units for the relation that triggered the current hook.

  • app – List remote application instead of participating units.

ops.hookcmds.relation_model_get(id: int | None = None) → RelationModel[source]

Get details about the model hosting a related application.

Note that id can only be None if the current hook is a relation event, in which case Juju will use the ID of the relation that triggered the event.

For more details, see: Juju | Hook commands | relation-model-get

Parameters:

id – The ID of the relation to get data for, or None to get data for the relation that triggered the current hook.

ops.hookcmds.relation_set(
data: Mapping[str, str],
id: int | None = None,
*,
app: bool = False,
)[source]

Set relation settings.

Setting the value for a key to the empty string deletes that key. The data is updated with the values provided, not replaced, so any keys that are not specified are left unchanged.

Note that id can only be None if the current hook is a relation event, in which case Juju will use the ID of the relation that triggered the event.

For more details, see: Juju | Hook commands | relation-set

Parameters:

  • data – The relation data to set.

  • id – The ID of the relation to set data for, or None to set data for the relation that triggered the current hook.

  • app – Set data for the overall application, not just a unit.

ops.hookcmds.resource_get(name: str) → Path[source]

Get the path to the locally cached resource file.

For more details, see: Juju | Hook commands | resource-get

Parameters:

name – The name of the resource.

ops.hookcmds.secret_add(
content: dict[str, str],
*,
label: str | None = None,
description: str | None = None,
expire: datetime | str | None = None,
rotate: Literal['never', 'hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | None = None,
owner: Literal['application', 'unit'] = 'application',
) → str[source]

Add a new secret.

For more details, see: Juju | Hook commands | secret-add

Parameters:

  • content – The content of the secret.

  • label – A label used to identify the secret in hooks.

  • description – The secret description.

  • expire – Either a duration or time when the secret should expire.

  • rotate – The secret rotation policy.

  • owner – The owner of the secret, either the application or the unit.

ops.hookcmds.secret_get(
*,
id: str | None = None,
label: str | None = None,
refresh: bool = False,
peek: bool = False,
) → dict[str, str][source]

Get the content of a secret.

Either the ID or the label or both must be provided. If both are provided, the secret is looked up by ID and the label is set to the one provided.

For more details, see: Juju | Hook commands | secret-get

Parameters:

  • id – The ID of the secret to retrieve.

  • label – The label of the secret to retrieve.

  • peek – Get the latest revision just this time.

  • refresh – Get the latest revision and also get this same revision for subsequent calls.

ops.hookcmds.secret_grant(id: str, relation_id: int, *, unit: str | None = None)[source]

Grant access to a secret.

For more details, see: Juju | Hook commands | secret-grant

Parameters:

  • id – The ID of the secret to grant access to.

  • relation_id – The relation with which to associate the grant.

  • unit – If provided, limit access to just that unit.

ops.hookcmds.secret_ids() → list[str][source]

Retrieve IDs for secrets owned by the application.

For more details, see: Juju | Hook commands | secret-ids

ops.hookcmds.secret_info_get(
*,
id: str | None = None,
label: str | None = None,
) → SecretInfo[source]

Get a secret’s metadata info.

Either the ID or the label must be provided.

For more details, see: Juju | Hook commands | secret-info-get

Parameters:

  • id – The ID of the secret to retrieve.

  • label – The label of the secret to retrieve.

ops.hookcmds.secret_remove(id: str, *, revision: int | None = None)[source]

Remove an existing secret.

For more details, see: Juju | Hook commands | secret-remove

Parameters:

  • id – The ID of the secret to remove.

  • revision – The revision of the secret to remove. If not provided, all revisions are removed.

ops.hookcmds.secret_revoke(
id: str,
*,
relation_id: int | None,
app: str | None,
unit: str | None = None,
)[source]

Revoke access to a secret.

For more details, see: Juju | Hook commands | secret-revoke

Parameters:

  • id – The ID of the secret.

  • relation_id – The relation for which to revoke the grant.

  • app – Revoke access from all units in that application.

  • unit – Revoke access from just this unit.

ops.hookcmds.secret_set(
id: str,
*,
content: dict[str, str] | None = None,
label: str | None = None,
description: str | None = None,
expire: datetime | str | None = None,
rotate: Literal['never', 'hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | None = None,
owner: Literal['application', 'unit'] = 'application',
)[source]

Update an existing secret.

For more details, see: Juju | Hook commands | secret-set

Parameters:

  • id – The ID of the secret to update.

  • content – The content of the secret.

  • label – A label used to identify the secret in hooks.

  • description – The secret description.

  • expire – Either a duration or time when the secret should expire.

  • rotate – The secret rotation policy.

  • owner – The owner of the secret, either the application or the unit.

ops.hookcmds.state_delete(key: str)[source]

Delete server-side-state key value pairs.

For more details, see: Juju | Hook commands | state-delete

Parameters:

key – The key of the server-side state to delete.

ops.hookcmds.state_get(key: str | None) → dict[str, str] | str[source]

Get server-side-state value.

For more details, see: Juju | Hook commands | state-get

Parameters:

key – The key of the server-side state to get. If None, get all keys and values.

ops.hookcmds.state_set(data: Mapping[str, str])[source]

Set server-side-state values.

For more details, see: Juju | Hook commands | state-set

Parameters:

data – The key-value pairs to set in the server-side state.

ops.hookcmds.status_get(
*,
app: bool = False,
) → AppStatus | UnitStatus[source]

Get a status of a unit or an application.

For more details, see: Juju | Hook commands | status-get

Parameters:

app – Get status for all units of this application if this unit is the leader.

ops.hookcmds.status_set(
status: Literal['active', 'blocked', 'maintenance', 'waiting'],
message: str | None = None,
*,
app: bool = False,
)[source]

Set a status of a unit or an application.

For more details, see: Juju | Hook commands | status-set

Parameters:

  • status – The status to set.

  • message – A message to include in the status.

  • app – If True, set this status for the application to which the unit belongs.

ops.hookcmds.storage_add(counts: Mapping[str, int])[source]

Add storage instances.

For more details, see: Juju | Hook commands | storage-add

Parameters:

counts – A maps of storage names to the number of instances of that storage to create.

ops.hookcmds.storage_get(id: str | None = None) → Storage[source]

Retrieve information for the storage instance with the specified ID.

Note that id can only be None if the current hook is a storage event, in which case Juju will use the ID of the storage that triggered the event.

For more details, see: Juju | Hook commands | storage-get

Parameters:

id – The ID of the storage instance.

ops.hookcmds.storage_list(name: str | None = None) → list[str][source]

List storage attached to the unit.

For more details, see: Juju | Hook commands | storage-list

Parameters:

name – Only list storage with this name.