Utilities for Extension Authors¶
-
outgoing.
lookup_netrc
(host: str, username: Optional[str] = None, path: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = 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: Union[str, Mapping[str, Any]], host: Optional[str] = None, username: Optional[str] = None, configpath: Optional[Union[str, pathlib.Path]] = 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: Union[str, bytes, os.PathLike[str], os.PathLike[bytes]], basepath: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = None) → pathlib.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.ABC
,pydantic.main.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
[source]¶ 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] 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
-
configpath
: Optional[outgoing.config.Path]¶
-
netrc
: Union[pydantic.types.StrictBool, outgoing.config.FilePath]¶
-
password
: Optional[outgoing.config.StandardPassword]¶