General documentation

App

class pyqos.PyQoS(app_name='pyqos', root_path=None)[source]

Application to simplify the initialization of the QoS rules. Inspired from the Flask project.

Usually you create a PyQoS instance in your main module or in the __init__.py file of your package like this:

from pyqos import PyQoS
app = PyQoS(application_name)
debug

set the main logger in debug mode or not

default_config = {'DEBUG': False, 'DRYRUN': False, 'INTERFACES': {}, 'LOGGER_NAME': None}

configuration default values

dryrun

dryrun

init_parser()[source]

Init argparse objects

logger

A logging.Logger object for this application. The default configuration is to log to stderr if the application is in debug mode. This logger can be used to (surprise) log messages. Here some examples:

app.logger.debug('A value for debugging')
app.logger.warning('A warning occurred (%d apples)', 42)
app.logger.error('An error occurred')
logger_name

name of the main logger

reset_qos()[source]

Reset QoS for all configured interfaces

run_as_root()[source]

Restart the script as root

run_list = []

list of qos object to apply at run

Backend

TC

pyqos.backend.tc.filter(interface, action, prio, handle, flowid, parent=None, protocol='all', dryrun=False, *args, **kwargs)[source]

Add/change/replace/delete filter

**kwargs will be used for specific arguments, depending on the algorithm used.

Parameters:
  • action – “add”, “replace”, “change” or “delete”
  • interface – target interface
  • prio – priority
  • handle – filter id
  • flowid – target class
  • parent – parent class/qdisc (default: None)
  • protocol – protocol to filter. (default: “all”)
pyqos.backend.tc.filter_add(interface, parent, prio, handle, flowid, protocol='all', *args, **kwargs)[source]

Add filter

**kwargs will be used for specific arguments, depending on the algorithm used.

Parameters:
  • interface – target interface
  • parent – parent class/qdisc
  • prio – priority
  • handle – filter id
  • flowid – target class
  • protocol – protocol to filter (default: “all”)
pyqos.backend.tc.filter_del(interface, prio, handle, flowid, parent=None, protocol='all', *args, **kwargs)[source]

Delete filter

**kwargs will be used for specific arguments, depending on the algorithm used.

Parameters:
  • interface – target interface
  • prio – priority
  • handle – filter id
  • flowid – target class
  • parent – parent class/qdisc (default: None)
  • protocol – protocol to filter (default: “all”)
pyqos.backend.tc.filter_show(interface, dryrun=False)[source]

Show filters

Parameters:interface – target interface
pyqos.backend.tc.qdisc(interface, action, algorithm=None, handle=None, parent=None, stderr=None, dryrun=False, opts_args=None, **kwargs)[source]

Add/change/replace/replace qdisc

**kwargs will be used for specific arguments, depending on the algorithm used.

Parameters:
  • action – “add”, “replace”, “change” or “delete”
  • interface – target interface
  • algorithm – algorithm used for this leaf (htb, pfifo, sfq, …)
  • handle – handle parameter for tc (default: None)
  • parent – if is None, the rule will be added as root. (default: None)
  • stderr – indicates stderr to use during the tc commands execution
  • opts_args – list of options without value, to append to the command
pyqos.backend.tc.qdisc_add(interface, handle, algorithm, parent=None, opts_args=None, **kwargs)[source]

Add qdisc

**kwargs will be used for specific arguments, depending on the algorithm used.

Parameters:
  • interface – target interface
  • algorithm – algorithm used for this leaf (htb, pfifo, sfq, …)
  • handle – handle parameter for tc
  • parent – if is None, the rule will be added as root. (default: None)
  • opts_args – list of options without value, to append to the command
pyqos.backend.tc.qdisc_del(interface, algorithm=None, handle=None, parent=None, *args, **kwargs)[source]

Delete qdisc

**kwargs will be used for specific arguments, depending on the algorithm used.

Parameters:
  • interface – target interface
  • algorithm – algorithm used for this leaf (htb, pfifo, sfq, …)
  • handle – handle parameter for tc (default: None)
  • parent – if is None, the rule will be added as root. (default: None)
pyqos.backend.tc.qdisc_show(interface=None, show_format=None, dryrun=False)[source]

Show qdiscs

Parameters:
  • show_format – option “FORMAT” for tc. (default: None) “stats” -> -s “details” -> -d “raw” -> -r “pretty” -> -p “iec” -> -i
  • interface – target interface (default: None)
pyqos.backend.tc.qos_class(interface, action, parent, classid=None, algorithm='htb', dryrun=False, *args, **kwargs)[source]

Add/change/replace/replace class

**kwargs will be used for specific arguments, depending on the algorithm used. Parameters need to be in kbit. If the unit isn’t indicated, add it automagically

Parameters:
  • action – “add”, “replace”, “change” or “delete”
  • interface – target interface
  • parent – parent class/qdisc
  • classid – id for the current class (default: None)
  • algorithm – algorithm used for this class (default: htb)
pyqos.backend.tc.qos_class_add(interface, parent, classid, algorithm='htb', **kwargs)[source]

Add class

**kwargs will be used for specific arguments, depending on the algorithm used. Parameters need to be in kbit. If the unit isn’t indicated, add it automagically

Parameters:
  • interface – target interface
  • parent – parent class/qdisc
  • classid – id for the current class (default: None)
  • algorithm – algorithm used for this class (default: htb)
pyqos.backend.tc.qos_class_del(interface, parent, classid=None, algorithm='htb', **kwargs)[source]

Delete class

**kwargs will be used for specific arguments, depending on the algorithm used. Parameters need to be in kbit. If the unit isn’t indicated, add it automagically

Parameters:
  • interface – target interface
  • parent – parent class/qdisc
  • classid – id for the current class (default: None)
  • algorithm – algorithm used for this class (default: htb)
pyqos.backend.tc.qos_class_show(interface, show_format=None, dryrun=False)[source]

Show classes

Parameters:
  • interface – target interface
  • show_format – option “FORMAT” for tc. (default: None) “stats” -> -s “details” -> -d “raw” -> -r “pretty” -> -p “iec” -> -i

Config

class pyqos.config.Config(root_path, defaults=None)[source]

Works like a dict but can be filled directly from a python configuration file. Inspired from the Flask Config class (a part of their code has been copied here).

Only uppercase keys are added to the config. This makes it possible to use lowercase values in the config file for temporary values that are not added to the config or to define the config keys in the same file that implements the application.

Parameters:
  • root_path – path to which files are read relative from. When the config object is created by the application, this is the application’s root_path.
  • defaults – an optional dictionary of default values
clear() → None. Remove all items from D.
copy() → a shallow copy of D
from_object(obj)[source]

Updates the values from the given object. An object can be of one of the following two types:

  • a string: in this case the object with that name will be imported
  • an actual object reference: that object is used directly

Objects are usually either modules or classes. Just the uppercase variables in that object are stored in the config. Example usage:

app.config.from_object('yourapplication.default_config')
from yourapplication import default_config
app.config.from_object(default_config)

You should not use this function to load the actual configuration but rather configuration defaults. The actual config should be loaded with from_pyfile() and ideally from a location not within the package because the package might be installed system wide.

Parameters:obj – an import name or object
from_pyfile(filename, silent=False)[source]

Updates the values in the config from a Python file. This function behaves as if the file was imported as module with the from_object() function.

Parameters:
  • filename – the filename of the config. This can either be an absolute filename or a filename relative to the root path.
  • silent – set to True if you want silent failure for missing files.
fromkeys()

Create a new dictionary with keys from iterable and values set to value.

get()

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault()

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values
class pyqos.config.ConfigAttribute(name, get_converter=None)[source]

Makes an attribute forward to the config

Again, copied from the Flask project

Decorators

pyqos.decorators.multiple_interfaces(f)[source]

Handle multiple interfaces for tc

If the parameter “interface” is a list of multiple interfaces, it will execute the function f for each interface

Exceptions

exception pyqos.exceptions.BadAttributeValueException[source]
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pyqos.exceptions.NoParentException[source]
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Tools

pyqos.tools.get_child_qdiscid(classid)[source]

Return the id to handle for a child qdisc. By convention, it will take its parent class id

Parameters:classid – parent class id
pyqos.tools.get_mtu(ifname)[source]

Use socket ioctl call to get MTU size of an interface

pyqos.tools.launch_command(command, stderr=None, dryrun=False)[source]

If the script is launched in debug mode, just prints the command. Otherwise, starts it with subprocess.call()