Simple bandwidth watching tool
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


bwatch - Simple bandwidth monitor


bwatch is a simple bandwidth monitor that can be used to keep track of network usage on interfaces, it was designed as a quick solution to tracking metered 3G connections. It is written in Python and licensed under the GPL v3.

Why write a new tool? A realisation that a tool that exactly meets my requirements could be written in an hour or so, much less time it would take to patch existing tools.


bwatch does not depend on any modules that aren't included in Python's standard library, and as such should run with Python 2.5 or newer [1]. . If bwatch doesn't work with the version of Python you have installed, drop me a mail and I'll endeavour to fix it.

It has only been tested on Linux, but you're more than welcome to fix it to work on your platform of choice. The modules and scripts contain a large collection of doctest tests that can be checked with ./setup test_code, and the code examples in the documentation can be tested with ./setup test_doc.

[1]If you still use Python v2.4 only small changes are required, for example changing the date parsing routine as datetime objects don't have strptime in 2.4 and fixing the import for parseaddr. Patches are welcome, but at this point I no longer 2.4 compatibility myself.
[2]Some tests may fail due to rounding errors depending on the system the tests are being run on, but such instances should be obvious even to the casual user and some effort has been put in to reduce the likelihood of such failures.


The simplest way to show how bwatch works is by example, and here goes:

$ bwatch
<insert output here>

All the class definitions, methods and independent functions contain hopefully useful usage examples in the docstrings.

All the examples in the doc/ directory can be executed using ./ test_doc.


The following people have submitted patches, testing and feedback:

  • You? - Your name here

API Stability

API stability isn't guaranteed across versions, although frivolous changes won't be made.

When bwatch 1.0 is released the API will be frozen, and any changes which aren't backwards compatible will force a major version bump.



Patches are most welcome, but I'd appreciate it if you could follow the guidelines below to make it easier to integrate your changes. These are guidelines however, and as such can be broken if the need arises or you just want to convince me that your style is better.

  • PEP 8, the style guide, should be followed where possible.
  • While support for Python versions prior to v2.5 may be added in the future if such a need were to arise, you are encouraged to use v2.5 features now.
  • All new classes and methods should be accompanied by new doctest examples, and epydoc's epytext formatted descriptions if at all possible.
  • Tests must not span network boundaries, see test.mock for workarounds.
  • doctest tests in modules are only for unit testing in general, and should not rely on any modules that aren't in Python's standard library.
  • Functional tests should be in the doc directory in reStructuredText formatted files, with actual tests in doctest blocks. Functional tests can depend on external modules, but they must be Open Source.

New examples for the doc directory are as appreciated as code changes.


If you find any problems, bugs or just have a question about this package either drop me a mail or file an issue. Locally bugs are managed with ditz, so if you're working with a clone of the repository you can report, list and fix bugs using ditz.

If you've found please attempt to include a minimal testcase so I can reproduce the problem, or even better a patch!