score.cli

This module provides features for conveniently developing command line interfaces to other modules. It makes use of the excellent click library.

Quickstart

Note

The tutorial provides a more elaborate introduction to this module, so check it out if you haven’t already.

This example will create a function for listing all initialized modules. We want it to ba callable as score modules.

First, you need a function that handles the logic. We will assume, the next function is in the python module beekeeper:

from random import randint

@click.group
@click.pass_context
def main(clickctx):
    """
    Lists all configured modules
    """
    score = clickctx.obj['conf'].load()
    for module in score._modules:
        print(module)
        if randint(1, 10) == 1:
            print('shhhh!')

The only other thing you need is an entry point declaration in your package’s setup.py:

setup(
    # ... some other stuff
    entry_points={
        'score.cli': [
            'modules = beekeeper:main',
        ],
    },
    # ... potentially more stuff
)

Configuration

This is one of the few modules, that have no initializer: It is just here for taking care of shell commands.

Details

CLI Command Aggregation

This module allows exposing a command line interface and grants access to all such exposed interfaces via a command line application called score. If a module called foo allows clearing its cache via CLI, this feature might be available via the following console command:

$ score foo clear-cache

Every module may register a click.Command in its setup.py using setuptools’ formidable feature for Dynamic Discovery of Services and Plugins. The foo module just needs to add these lines to its setup.py to expose the click.Command called main in the package foo.cli:

from setuptools import setup, find_packages
setup(
    # ...
    entry_points={
        'score.cli': [
            'foo = foo.cli:main',
        ]
    },
    # ...

Configuration Management

Another feature provided by this module is easy management of configuration files for command line applications: we assume that you initialize score using the same configuration file most of the time. You can manage your configurations using the conf subcommand:

$ score conf list
spam
cheeseshop *

This command will give you a list of available configurations in your current environment. The asterisk indicates that cheeseshop is the default configuration, i.e. will be used implicitly, if you don’t specify an alternate configuration explicitly.

You can add further configurations to this list using the conf subcommand: Setting a value is as simple as calling the appropriate CLI command:

$ score conf add sketches/parrot.conf
$ score conf list
spam
cheeseshop *
parrot

This command will register the given file under the name parrot (the filename without its extension). It is possible to store the file under a different name by passing a --name parameter. You can also pass the --paths option to display the location of each file:

$ score conf remove parrot
$ score conf add --name birdie sketches/parrot.conf
$ score conf setdefault spam
$ score conf list --paths
spam * (/home/sirlancelot/sketches/parrot.conf)
cheeseshop   (/home/sirlancelot/sketches/cheeseshop.conf)
birdie   (/home/sirlancelot/sketches/parrot.conf)

Initializing SCORE

All command line applications can access the score configuration file in click’s context object. Performing a sketch through the CLI might be implemented the following way:

@click.group('sketch')
def sketch():
    pass

@sketch.command
@click.pass_context
def perform(clickctx):
    score = clickctx.obj['conf'].load()
    score.sketch.perform()

$ score conf list
spam *
cheeseshop
birdie
$ score sketch perform
Spam, Spam, Spam, lovely Spam
Wonderful Spam, Lovely Spam.
Spam, Spam, Spam, magnificent Spam,
...
$ score -c birdie sketch perform
Mr. Praline: 'Ello, I wish to register a complaint.
Mr. Praline: 'Ello, Miss?
Owner: What do you mean "miss"?
...

Configuration Locations

All your configuration files are stored in your a folder called .score in your home folder. Developers may make use of various helper functions provided by this modules to store various configurations. The configuration files, as described above, are in a sub-folder called conf:

$ ls ~/.score/conf
 __default__  __global__

The __global__ configuration file will always be evaluated, whereas the __default__ configuration is merely a pointer to your current configuration. The other files are those you configured yourself.

Usually, though, this folder just contains the __global__ and __default__ configuration. The reason is that any configuration files you register while inside a virtual environment are registered in a different folder: the root folder of the currently active virtual environment:

(sketches)$ ls $VIRTUAL_ENV/.score/conf
birdie  cheeseshop  __default__  spam

API

score.cli.conf.venv_root(venv=None)

Provides the root folder of the current virtual environment.

Returns None, if this python process is not running inside a virtual environment.

In order to provide a similar interface to the other functions in this package, it also accepts a venv parameter. Since that parameter is expected to be the root of a virtual environment, it will be returned, if it is passed.

score.cli.conf.rootdir(*, global_=False, venv=None)

Provides the current .score folder.

This function will determine the valid path of the configuration folder for the current environment, as described in the narrative documentation of the configuration locations.

It is possible to retrieve the configuration folder in one’s home directory by passing a truthy value for global_.

It is also possible to access the configuration folder of a different virtual environment by passing the venv parameter (the path to a virtual environment).

score.cli.conf.add(name, path, *, venv=None)

Adds a configuration with given name, pointing to the configuration file at path.

The name must not start with two underscores, must consist of alphanumeric characters, underscores and hyphens and must not start with a number or a hyphen. Will raise an InvalidConfigurationNameException violates these constraints.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.remove(name, *, venv=None)

Deletes the configuration with given name.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.make_default(name, *, venv=None)

Updates the current environment’s default configuration to point to the configuration with given name.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.get_file(name, *, venv=None)

Returns the file the configuration with given name is pointing to.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.get_default(*, venv=None)

Returns the name of the default configuration.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.name2file(*, include_global=True, venv=None)

Returns the names of all available configurations.

Will list all configurations in the current virtual environment, as well as all global configuration files, unless include_global is False.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.global_file()

Returns the path to the global configuration file.

Although the return value of this function is always the same, it ensures that the file actually exists by creating it with some informative comments.

score.cli.conf.default_file(*, global_=False, venv=None)

Returns the path to the default configuration in the current environment.

This function will create that file, if it does not exist.

Can also operate on a given virtual environment if the venv parameter is not None. The specifics of this behaviour is documented in rootdir().

score.cli.conf.get_origin(file)

Parses given configuration file and finds the file this one is based_on.