sdsstools 0.1.2

Small tools for SDSS products

sdsstools

sdsstools provides several common tools for logging, configuration handling, version parsing, packaging, etc. It's main purpose is to consolidate some of the utilities originally found in the python_template, allowing them to become dependencies that can be updated.

This is not intended to be a catch-all repository for astronomical tools. sdsstools itself aims to have minimal dependencies (i.e., mainly the Python standard library and setuptools).

Using sdsstools

To use sdsstools simply install it with

pip install sdsstools

Most likely, you'll want to include sdsstools as a dependency for your library. To do so, either add to your setup.cfg

[options]
install_requires =
    sdsstools>=0.1.0

(this is equivalent of passing install_requires=['sdsstools>=0.1.0'] to setuptools.setup), or if you are using poetry run poetry add sdsstools, which should add this line to your pyproject.toml

[tool.poetry.dependencies]
sdsstools = { version="^0.1.0" }

Logging

sdsstools includes the sdsstools.logger.SDSSLogger class, which provides a wrapper around the standard Python logging module. SDSSLoger provides the following features:

• A console handler (accessible via the .sh attribute) with nice colouring.
• Automatic capture of warnings and exceptions, which are formatted and redirected to the logger. For the console handler, this means that once the logger has been created, all warnings and exceptions are output normally but are clearer and more aesthetic.
• A TimedRotatingFileHandler (accessible via the .fh attribute) that rotates at midnight UT, with good formatting.

To get a new logger for your application, simply do

from sdsstools.logger import get_logger

NAME = 'myrepo'
log = get_logger(NAME)

The file logger is disabled by default and can be started by calling log.start_file_logger(path).

Configuration

The sdsstools.configuration module contains several utilities to deal with configuration files. The most useful one is get_config, which allows to read a YAML configuration file. For example

from sdsstools.configuration import get_config

NAME = 'myrepo'
config = get_config(NAME, allow_user=True)

get_config assumes that the file is located in etc/<NAME>.yml relative from the file that calls get_config, but that can be changed by passing config_file=<config-file-path>. Additionally, if allow_user=True and a file exists in ~/.config/<NAME>/<NAME>.yaml, this file is read and merged with the default configuration, overriding any parameter that is present in the user file. This allows to create a default configuration that lives with the library but that can be overridden by a user.

Additionally, sdsstools.configuration includes two other tools, merge_config, that allows to merge dictionaries recursively, and read_yaml_file, to read a YAML file.

Metadata

sdsscore provides tools to locate and parse metadata files (pyproject.toml, setup.cfg, setup.py). get_metadata_files locates the path of the metadata file relative to a given path. get_package_version tries to find the version of the package by looking for a version string in the metadata file or in the egg/wheel metadata file, if the package has been installed. To use it

from sdsstools.metadata import get_package_version

__version__ = get_package_version(path=__file__, package_name='sdss-camera') or 'dev'

This will try to find and parse the version from the metadata file (we pass __file__ to indicate where to start looking); if that fails, it will try to get the version from the installed package sdss-camera. If all fails, it will set the fallback version 'dev'.

Command Line Interface

sdsstools provides the command line tool sdss, which is just a thin wrapper around some commonly used Invoke tasks. Because sdsstools tries very hard not to install unnecessary dependencies, and the CLI should only be useful for development, you'll need to run pip install sdsscore[dev] to be able to use sdss.

sdss provides the following tasks

Task	Options	Description
clean		Removes files produces during build and packaging
deploy	--test	Builds and deploys to PyPI (or the test server)
install-deps	--extras	Installs dependencies from a setup.cfg file
docs.build	--target	Builds the Sphinx documentation
docs.show	--target	Shows the documentation in the browser
docs.clean	--target	Cleans the documentation build

sdss assumes that the documentation lives in docs/sphinx relative to the root of the repository. This can be changed by setting the sphinx.target configuration in an invoke.yaml file, for example

sphinx:
    target: docs

Bundled packages

For convenience, sdsstools bundles the following products:

• A copy of releases that fixes some issues with recent versions of semantic-version.
• A copy of toml to read TOML files (used by the metadata submodule).

You can access them directly from the top-level namespace, sdsstools.toml, sdsstools.releases. To use releases with sphinx, simply add the following to your config.py

extensions += ['sdsstools.releases']