Utilities for Extension Authors
- outgoing.lookup_netrc(host: str, username: str | None = None, path: str | bytes | PathLike[str] | PathLike[bytes] | None = None) → tuple[str, str][source]
Look up the entry for
host
in the netrc file atpath
(default:~/.netrc
) and return a pair of the username & password. Ifusername
is specified and it does not equal the username in the file, aNetrcLookupError
is raised.- Raises:
NetrcLookupError – if no entry for
host
or the default entry is present in the netrc file; or ifusername
differs from the username in the netrc filenetrc.NetrcParseError – if the
netrc
module encounters an error
- outgoing.resolve_password(password: str | Mapping[str, Any], host: str | None = None, username: str | None = None, configpath: str | Path | None = None) → str[source]
Resolve a configuration password value. If
password
is a string, it is returned unchanged. Otherwise, it must be a mapping with exactly one element; the key is used as the name of the password scheme, and the value is passed to the corresponding function for retrieving the password.When resolving a password field in an
outgoing
configuration structure, the configpath and any host/service or username values from the configuration (or host/service/username constants specific to the sending method) should be passed into this function so that they can be made available to any password scheme functions that need them.- Raises:
InvalidPasswordError – if
password
is invalid or cannot be resolved
- outgoing.resolve_path(path: str | bytes | PathLike[str] | PathLike[bytes], basepath: str | bytes | PathLike[str] | PathLike[bytes] | None = None) → Path[source]
Convert a path to a
pathlib.Path
instance and resolve it using the same rules for as paths inoutgoing
configuration files: expand tildes by callingPath.expanduser()
, prepend the parent directory ofbasepath
(usually the value ofconfigpath
) to the path if given, and then resolve the resulting path to make it absolute.- Parameters:
path (path) – the path to resolve
basepath (path) – an optional path to resolve
path
relative to
- Return type:
- class outgoing.OpenClosable[source]
Bases:
ABC
,BaseModel
An abstract base class for creating reentrant context managers. A concrete subclass must define
open()
andclose()
methods;OpenClosable
will then define__enter__
and__exit__
methods that keep track of the depth of nestedwith
statements, callingopen()
andclose()
only when entering & exiting the outermostwith
.
Pydantic Types & Models
The senders built into outgoing
make heavy use of pydantic for validating
& processing configuration, and some of the custom types & models used are also
of general interest to anyone writing an outgoing
extension that also uses
pydantic.
- class outgoing.Path
Converts its input to
pathlib.Path
instances, including expanding tildes. If there is a field namedconfigpath
declared before thePath
field and its value is non-None
, then the value of thePath
field will be resolved relative to the parent directory of theconfigpath
field; otherwise, it will be resolved relative to the current directory.
- class outgoing.Password[source]
A subclass of
pydantic.SecretStr
that acceptsoutgoing
password specifiers as input and automatically resolves them usingresolve_password()
. Host, username, andconfigpath
values are passed toresolve_password()
as follows:If
Password
is subclassed and given ahost
class variable naming a field, and if the subclass is then used in a model where a field with that name is declared before thePassword
subclass field, then when the model is instantiated, the value of the named field will be passed as thehost
argument toresolve_password()
. (If the named field is not present on the model that uses the subclass, thePassword
field will fail validation.)Alternatively,
Password
can be subclassed withhost
set to a class callable (a classmethod or staticmethod), and when that subclass is used in a model being instantiated, the callable will be passed adict
of all validated fields declared before the password field; the return value from the callable will then be passed as thehost
argument toresolve_password()
. (If the callable raises an exception, thePassword
field will fail validation.)If
Password
is used in a model without being subclassed, or ifhost
is not defined in a subclass, thenNone
will be passed as thehost
argument toresolve_password()
.The
username
argument toresolve_password()
can likewise be defined by subclassingPassword
and definingusername
appropriately.If there is a field named
configpath
declared before thePassword
field, then the value ofconfigpath
is passed toresolve_password()
.
For example, if writing a pydantic model for a sender configuration where the host-analogue value is passed in a field named
"service"
and for which the username is always"__token__"
, you would subclassPassword
like this:class MyPassword(outgoing.Password): host = "service" @staticmethod def username(values: dict[str, Any]) -> str: return "__token__"
and then use it in your model like so:
class MySender(pydantic.BaseModel): configpath: Optional[outgoing.Path] = None service: str password: MyPassword # Must come after `configpath` and `service`! # ... other fields ...
Then, when
MySender
is instantiated, the input to thepassword
field would be automatically resolved by doing (effectively):my_sender.password = pydantic.SecretStr( resolve_password( my_sender.password, host=my_sender.service, username="__token__", configpath=my_sender.configpath, ) )
Note
As this is a subclass of
pydantic.SecretStr
, the value of aPassword
field is retrieved by calling itsget_secret_value()
method.
- class outgoing.StandardPassword[source]
A subclass of
Password
in whichhost
is set to"host"
andusername
is set to"username"
- class outgoing.NetrcConfig[source]
A pydantic model usable as a base class for any senders that wish to support both
password
fields and netrc files. The model accepts the fieldsconfigpath
,netrc
(a boolean or a file path; defaults toFalse
),host
(required),username
(optional), andpassword
(optional). When the model is instantiated, ifpassword
isNone
butnetrc
is true or a filepath, the entry forhost
is looked up in~/.netrc
or the given file, and theusername
andpassword
fields are set to the values found.The model will raise a validation error if any of the following are true:
password
is set butnetrc
is truepassword
is set butusername
is not setusername
is set butpassword
is not set andnetrc
is falsenetrc
is true or a filepath,username
is non-None
, and the username in the netrc file differs fromusername
netrc
is true or a filepath and no entry can be found in the netrc file
- password: StandardPassword | None