This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
# cmdline
The cmdline package provides a standard way to specify and override command settings and logging configuration. Using cmdline setttings is as simple as creating a `settings.yml`:
```
REMOTE_ADDR:
default: 'https://example.com/'
help: the remote address
```
and compiling the settings in your main program:
```
from cmdline import SettingsParser, settings


def main():
SettingsParser.compile_settings()

remote = settings.REMOTE_ADDR

print('remote addr:', remote)


if __name__ == '__main__':
sys.exit(main())
```
Your program can then be called in any of the following ways:
```
$ remote
remote addr: https://example.com/
$ export REMOTE_ADDR=https://env.example.com/
$ remote
remote addr: https://env.example.com/
$ remote --remote-addr=https://arg-takes-precedence.example.com/
remote addr: https://arg-takes-precedence.example.com/
```

## Installation
```
pip install cmdline
```

## Settings
Settings are configured in an overlaid fashion starting with a root configuration packaged with the application. Standard [argparse](https://docs.python.org/3/library/argparse.html) options are used to configure settings.

### Override defaults
The packaged settings can be overridden by additional settings files on the filesystem, environment variables, and finally command line arguments. For a command named `remote` order in which they are applied are:

- packaged settings
- <sys.prefix>/etc/remote/settings.yml
- ~/.remote/settings.yml
- environment variables
- command line arguments

Environment variables map exactly to the name of the setting, i.e. the environment variable `REMOTE_ADDR` configures the `REMOTE_ADDR` setting.

Command line arguments are lowercase-dashed versions of the setting, for instance, the command line argument `--remote-addr` configures the `REMOTE_ADDR` setting.

### Subcommands
The settings parser supports [argparse subcommands](https://docs.python.org/3/library/argparse.html#sub-commands) A setting can be configured to be for a subcommand by adding a `_subcommand` key to the setting's options. For example:
```
COPY_FORCE
default: no
_subcommand: copy
```
The `_SUBCOMMAND` setting contains the name of the subcommand the command was run with.

### Documentation
Command descriptions and help text can be added in a `_COMMANDS` section. The `_main` will set the description for the main program. Any other keys will correspond to a subcommand by the same name. For example, below sets the description for the main program and the description and help text for the `copy` subcommand:
```
_COMMANDS:
_main:
description: >
this is main description and can be a very long string
that covers multiple lines
copy:
description: >
this is copy subcommand description and can be a very long string
that covers multiple lines
help: copy files
```
### Type conversion
Settings can be converted to a particular type using argparse's `type` setting. For example setting `type: int` will convert the setting into an integer. This is done by using Python's built-in `int()` function.

When `type` is a dotted string, the given function will be imported and used. For example, setting `type: convesion.convert_bool` will call the `convert_bool()` function in the [conversion](https://pypi.python.org/pypi/conversion) package.

## Logging
Similarly, logging is configured through Python's `logging.config.dictConfig()` function. More info on dictconfig is at [docs.python.org](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig); an example is below. This configuration sets a `console` handler that sends logs to stdout and a `null` handler that throws away logs. The default logging configuration is to log WARN level and higher messages to the console, which is setup by the `root` logger, and two additional loggers are configured for the `mypkg.foo` and `mypkg.bar` loggers, where the loglevel for `mypkg.foo` is set to DEBUG and `mypkg.bar` is thrown out altogether.

```
version: 1
disable_existing_loggers: False

formatters:
simple:
format: "%(asctime)s %(name)s:%(lineno)d %(levelname)s %(message)s"


handlers:
console:
class: logging.StreamHandler
level: WARN
formatter: simple
stream: ext://sys.stdout

"null":
class: logging.NullHandler


loggers:
mypkg.foo:
level: DEBUG
handlers: [console]
propagate: no

mypkg.bar:
handlers: ["null"]
propagate: no


root:
level: WARN
handlers: [console]
```
Once the configuration is written, logging is configured by calling the `setup_logging()` function:
```
import logging
from cmdline import setup_logging


def main():
setup_logging()

logging.getLogger(__name__).warning('ello')


if __name__ == '__main__':
sys.exit(main())
```
### Log level environment
The only logging configuration that can be updated outside the configuration file is the default log level, which can be changed with the environment variable `LOG_LEVEL`; for example, `LOG_LEVEL=debug remote`.

## File location
Create a directory named `config`. In that directory, create the files `logconfig.yml` and `settings.yml`. A bare-bones `setup.py` that installs these files correctly is below:
```
#!/usr/bin/env python
import os

from setuptools import setup


def get_data_files(base):
for dirpath, dirnames, filenames in os.walk(base):
for filename in filenames:
yield os.path.join(dirpath, filename)


data_files = [
('config', list(get_data_files('config'))),
]

setup(name='remote',
version='0.0.1',
packages=['remote'],
data_files=data_files,
entry_points = {
'console_scripts': [
'remote = remote.command:main',
],
},
)
```
The file structure for the `setup.py` above looks like:
```
root_dir/
+- remote/
| +- __init__.py
| +- command.py
+- config/
| +- logconfig.yml
| +- settings.yml
+- setup.py
```
## Config root environment variable
Setting the environment variable `CMDLINE_CONFIG_ROOT` will make the given path the primary config location for settings and logging.
Release History

Release History

0.1.6

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.6

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
cmdline-0.1.6.tar.gz (6.6 kB) Copy SHA256 Checksum SHA256 Source Jun 30, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting