gavo.utils.ostricks module

OS abstractions and related.

This module contains, in partiular, the interface for having “easy subcommands” using argparse. The idea is to use the exposedFunction decorator on functions that should be callable from the command line as subcommands; the functions must all have the same signature. For example, if they all took the stuff returned by argparse, you could say in the module containing them:

args = makeCLIParser(globals()).parse_args()
args.subAction(args)

To specify the command line arguments to the function, use Args. See admin.py for an example.

class gavo.utils.ostricks.Arg(*args, **kwargs)

Bases: object

an argument/option to a subcommand.

These are constructed with positional and keyword parameters to the argparse’s add_argument.

add(parser)

class gavo.utils.ostricks.HTTPSHandler(debuglevel: int = 0, context: Optional[SSLContext] = None)

Bases: HTTPSHandler

class gavo.utils.ostricks.StatusDisplay(dest_f: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Bases: object

A context manager for updating a one-line display.

This shouldn’t be used from DaCHS proper (which should use base.ui.notify*), but it’s sometimes handy in helper scripts.

In short:

with StatusDisplay() as d:
        for i in range(300):
                d.update(str(i))

update(new_content: str) → None

gavo.utils.ostricks.cat(srcF: IO, destF: IO, chunkSize: int = 1048576) → None

reads srcF into destF in chunks.

gavo.utils.ostricks.ensureDir(dirPath: str, *, mode: Optional[int] = None, setGroupTo: Optional[int] = None) → None

makes sure that dirPath exists and is a directory.

If dirPath does not exist, it is created, and its permissions are set to mode with group ownership setGroupTo if those are given.

setGroupTo must be a numerical gid if given.

This function may raise all kinds of os.errors if something goes wrong. These probably should be handed through all the way to the user since when something fails here, there’s usually little the program can safely do to recover.

gavo.utils.ostricks.exposedFunction(argSpecs: List[Arg] = [], help: Optional[str] = None) → Callable

a decorator exposing a function to parseArgs.

argSpecs is a sequence of Arg objects. This defines the command line interface to the function.

The decorated function itself must accept a single argument, the args object returned by argparse’s parse_args.

gavo.utils.ostricks.fgetmtime(fileobj: IO) → float

returns the mtime of the file below fileobj (like os.path.getmtime, but without having to have a file name).

This raises an os.error if that file cannot be fstated.

gavo.utils.ostricks.makeCLIParser(functions: Dict[str, Any]) → ArgumentParser

returns a command line parser parsing subcommands from functions.

functions is a dictionary (as returned from globals()). Subcommands will be generated from all objects that have a subparseArgs attribute; furnish them using the commandWithArgs decorator.

This attribute must contain a sequence of Arg items (see above).

gavo.utils.ostricks.safeReplaced(fName: str, *, binary: bool = True) → Generator

opens fName for “safe replacement”.

Safe replacement means that you can write to the object returned, and when everything works out all right, what you have written replaces the old content of fName, where the old mode is preserved if possible. When there are errors, however, the old content remains.

gavo.utils.ostricks.safeclose(f: IO) → None

syncs and closes the python file f.

You generally want to use this rather than a plain close() before overwriting a file with a new version.

gavo.utils.ostricks.setUserAgent(userAgent: str) → None

sets the user agent string for requests through urlopenRemote.

This is a global setting and thus, in particular, nowhere near thread-safe.

gavo.utils.ostricks.urlopenRemote(url: str, *, data: Union[None, dict, str, bytes] = None, creds: Tuple[Optional[str], Optional[str]] = (None, None), timeout: int = 100) → BinaryIO

works like urllib.urlopen, except only http, https, and ftp URLs are handled.

The function also massages the error messages of urllib a bit. urllib errors always become IOErrors (which is more convenient within DaCHS).

creds may be a pair of username and password. Those credentials will be presented in http basic authentication to any server that cares to ask. For both reasons, don’t use any valuable credentials here.