Warning

This is the documentation for a development version of flagman.

Documentation for the Most Recent Stable Version

Welcome to flagman!

Perform arbitrary actions on signals.

$ flagman --usr1 print 'a fun message' --usr1 print 'another message' --usr2 print_once 'will be printed once' &
INFO:flagman.cli:PID: 49220
INFO:flagman.cli:Setting loglevel to WARNING
init  # the set_up phase of the three actions
init
init
$ kill -usr1 49220  # actions are called in the order they're passed in the arguments
a fun message
another message
$ kill -usr2 49220  # actions can remove themselves when no longer useful
will be printed once
cleanup  # the tear_down phase of the `print_once` action
WARNING:flagman.core:Received `ActionClosed`; removing action `PrintOnceAction`
# *snip* traceback
flagman.exceptions.ActionClosed: Only print once
$ kill -usr1 49220  # other actions are still here, though
a fun message
another message
$ kill 49220  # responds gracefully to shutdown requests
cleanup  # the tear_down phase of the two remaining actions
cleanup

On this page:

Features

• Safe execution of code upon receiving SIGHUP, SIGUSR1, or SIGUSR2
• Optional systemd integration–sends READY=1 message when startup is complete
• Complete mypy type annotations

Use Cases

The use cases are endless! But specifically, flagman is useful to adapt services that do not handle signals in a convenient way for your infrastructure.

I wrote flagman to solve a specific problem, examined in A Real-World Use.

The Anatomy of an Action

Learn how to create your own Actions!

• The Anatomy of an Action
  • The Action Class
  • “Closing” an Action
  • Registering an Action

Overlapping Signals

flagman attempts to handle overlapping signals in an intelligent manner. This algorithm is explained here:

• Overlapping Signals

A Real-World Use

An examination of the problem I built flagman to solve.

• A Real-World Use

CLI Reference

The CLI options for flagman are documented here.

• CLI Reference
  • Notes

API Reference

Information about the interfaces flagman exposes are here.

• API Reference
  • The Action Class
  • The Core Module
  • Errors and Exceptions
  • Built-in Actions
  • Types
  • The CLI Module
  • Systemd Notify Utilities

Installation

flagman has no required dependencies outside the Python Standard Library.

At the moment, installation must be performed via GitHub:

$ pip install git+https://github.com/scolby33/flagman.git

For prettier output for flagman --list, install the color extra:

$ pip install git+https://github.com/scolby33/flagman.git[color]

flagman targets Python 3 and tests with Python 3.7. Versions earlier than 3.7 are not guaranteed to work.

Changelog

flagman adheres to the Semantic Versioning (“Semver”) 2.0.0 versioning standard. Details about this versioning scheme can be found on the Semver website. Versions postfixed with ‘-dev’ are currently under development and those without a postfix are stable releases.

You are reading the documents for version 0.1.0-dev of flagman.

Changes as of 18 July 2018

• Initial implementation of the flagman functionality.

Contributing

There are many ways to contribute to an open-source project, but the two most common are reporting bugs and contributing code.

If you have a bug or issue to report, please visit the issues page on GitHub and open an issue there.

If you want to make a code contribution, feel free to open a pull request!

License

The systemd notification portion of flagman is originally Copyright © 2016 Brett Bethke and is provided under the MIT license. The original source is found at https://github.com/bb4242/sdnotify.

The remainder of flagman is Copyright © 2018 Scott Colby and is available under the MIT license.

See the LICENSE.rst file in the root of the source code repository for the full text of the license.

Indices and tables

• Index
• Module Index
• Search Page