Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documentation rework

  • Loading branch information...
commit 9fc5872618ed8d16f6a175b0de9c96a71d5aa306 1 parent 2cc46f3
@seveas authored
View
11 HACKING
@@ -9,12 +9,7 @@ Source preparation:
Packaging:
- ./setup.py sdist
- - dpkg-buildpackage -rfakeroot
- - Upload tarballs and packages to kaarsemaker.net
-
-pypi:
- - dh clean
- - cd docs/_build/html
- - rm -f docs.zip && zip -r docs.zip *
- - Upload docs.zip to pypi
+ - debuild -S
+ - Push to PPA
- ./setup.py register
+ - Regen gh-pages branch and push
View
1  MANIFEST.in
@@ -2,3 +2,4 @@ include docs/index.rst
include docs/Makefile
include docs/conf.py
include examples/*
+include COPYING
View
11 NetworkManager.py
@@ -1,3 +1,9 @@
+# NetworkManager - a library to make interacting with the NetworkManager daemon
+# easier.
+#
+# (C)2011-2013 Dennis Kaarsemaker
+# License: GPL3+
+
import dbus
import socket
import struct
@@ -160,7 +166,6 @@ def GetSecrets(self, name=None):
return self.make_proxy_call('GetSecrets')(name)
def postprocess(self, name, val):
- # SSID is sent as bytes, make it a string
if name == 'GetSettings':
if 'ssid' in val.get('802-11-wireless', {}):
val['802-11-wireless']['ssid'] = fixups.ssid_to_python(val['802-11-wireless']['ssid'])
@@ -201,7 +206,6 @@ class AccessPoint(NMDbusInterface):
interface_name = 'org.freedesktop.NetworkManager.AccessPoint'
def postprocess(self, name, val):
- # SSID is sent as bytes, make it a string
if name == 'Ssid':
return fixups.ssid_to_python(val)
@@ -290,6 +294,9 @@ def const(prefix, val):
return key.replace(prefix,'').lower()
raise ValueError("No constant found for %s* with value %d", (prefix, val))
+# Several fixer methods to make the data easier to handle in python
+# - SSID sent/returned as bytes (only encoding tried is utf-8)
+# - IP, Mac address and route metric encoding/decoding
class fixups(object):
@staticmethod
def ssid_to_python(ssid):
View
5 README
@@ -9,6 +9,11 @@ calls are forwarded to the correct interface.
See docs/index.rst for the documentation. An HTML version can be found on
http://packages.python.org/python-networkmanager/
+Requirements
+============
+Python 2.5 or newer (Python 3 is supported as well) and the python D-Bus
+bindings.
+
Quick install instructions
==========================
View
4 docs/conf.py
@@ -41,7 +41,7 @@
# General information about the project.
project = u'python-networkmanager'
-copyright = u'2011-2012, Dennis Kaarsemaker'
+copyright = u'2011-2013, Dennis Kaarsemaker'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -50,7 +50,7 @@
# The short X.Y version.
version = '0.9'
# The full version, including alpha/beta/rc tags.
-release = '0.9.5'
+release = '0.9.6'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
111 docs/index.rst
@@ -1,23 +1,21 @@
-Welcome to python-networkmanager's documentation!
-=================================================
+Python API to talk to NetworkManager
+====================================
-python-networkmanager wraps NetworkManagers D-Bus interface so you can be less
-verbose when talking to NetworkManager from python. All interfaces have been
-wrapped in classes, properties are exposed as python properties and function
-calls are forwarded to the correct interface.
+NetworkManager provides a detailed and capable D-Bus interface on the system
+bus. You can use this interface to query NetworkManager about the overall state
+of the network and details of network devices like current IP addresses or DHCP
+options, and to activate and deactivate network connections.
-I wrote it to reduce a 100-line python script to 50 lines. Not realizing that
-the library has more lines than the ones I removed. Oh well 😊
+python-networkmanager takes this D-Bus interface and wraps D-Bus interfaces in
+classes and D-Bus properties in python properties. It also provides a
+command-line utility to inspect the configuration and (de-)activate
+connections.
-As of version 0.9.2, python-networkmanager also ships a command-line utility
-called n-m, which allows you to manipulate NetworkManager's state from the
-command line.
-
-:mod:`NetworkManager` -- Easy communication with NetworkManager
----------------------------------------------------------------
+The :mod:`NetworkManager` module
+--------------------------------
.. module:: NetworkManager
- :platform: Linux systems with NetworkManager 0.90
- :synopsis: Talk to NetworkManager without being verbose
+ :platform: Linux systems with NetworkManager 0.9.x
+ :synopsis: Talk to NetworkManager from python
All the code is contained in one module: :mod:`NetworkManager`. Using it is as
simple as you think it is:
@@ -26,12 +24,23 @@ simple as you think it is:
>>> import NetworkManager
>>> NetworkManager.NetworkManager.Version
- '0.9.1.90'
+ '0.9.6.0'
NetworkManager exposes a lot of information via D-Bus and also allows full
control of network settings. The full D-Bus API can be found on `NetworkManager
project website`_. All interfaces listed there have been wrapped in classes as
-listed below.
+listed below. With a few exceptions, they behave exactly like the D-Bus
+methods. These exceptions are for convenience and limited to this list:
+
+* IP addresses are returned as strings of the form :data:`1.2.3.4` instead of
+ network byte ordered integers.
+* Route metrics are returned in host byte order, so you can use them as
+ integers.
+* Mac addresses and BSSIDs are always returned as strings of the form
+ :data:`00:11:22:33:44:55` instead of byte sequences.
+* Wireless SSID's are returned as strings instead of byte sequences. They will
+ be decoded as UTF-8 data, so using any other encoding for your SSID will
+ result in errors.
.. class:: NMDbusInterface
@@ -39,7 +48,9 @@ This is the base class for all interface wrappers. It adds a few useful
features to standard D-Bus interfaces:
* All D-Bus properties are exposed as python properties
-* Return values are automatically unwrapped (so no more :data:`dbus.String`)
+* Return values are automatically converted to python basic types (so no more
+ :data:`dbus.String`, but simple :data:`str` (python 3) or :data:`unicode`
+ (python 2))
* Object paths in return values are automatically replaced with proxy objects,
so you don't need to do that manually
* ...and vice versa when sending
@@ -48,7 +59,7 @@ features to standard D-Bus interfaces:
.. function:: const(prefix, value)
Many of NetworkManagers D-Bus methods expect or return numeric constants, for
-which there are enums in teh C sourece code only. These constants, such as
+which there are enums in the C source code. These constants, such as
:data:`NM_STATE_CONNECTED_GLOBAL`, can all be found in the
:mod:`NetworkManager` module as well. The :func:`const` function can help you
translate them to text. For example:
@@ -60,7 +71,7 @@ translate them to text. For example:
>>> NetworkManager.const('device_type', 2)
'wifi'
-.. _`NetworkManager project website`: http://projects.gnome.org/NetworkManager/developers/migrating-to-09/spec.html
+.. _`NetworkManager project website`: projects.gnome.org/NetworkManager/developers/api/09/spec.html
List of classes
---------------
@@ -102,9 +113,19 @@ interface.
.. class:: Bluetooth
+.. class:: OlpcMesh
+
.. class:: Wimax
-.. class:: OlpcMesh
+.. class:: Infiniband
+
+.. class:: Bond
+
+.. class:: Bridge
+
+.. class:: Vlan
+
+.. class:: Adsl
These classes represent D-Bus interfaces for various types of hardware. Note
that methods such as :data:`NetworkManager.GetDevices()` will only return
@@ -118,30 +139,50 @@ that methods such as :data:`NetworkManager.GetDevices()` will only return
[('eth0', 'Wired'), ('wlan0', 'Wireless'), ('wwan0', 'Modem')]
.. class:: IP4Config
+
.. class:: IP6Config
+.. class:: DHCP4Config
+
+.. class:: DHCP6Config
+
These classes represent the various IP configuration interfaces.
+.. class:: AgentManager
+
+.. class:: SecretAgent
+
+Classes that can be used to handle and store secrets. Note that these are not
+for querying NetworkManager's exisiting secret stores. For that the
+:func:`GetSecrets` method of the :class:`Connection` class can be used.
+
.. class:: VPNConnection
This class represents the :data:`org.freedesktop.NetworkManager.VPN.Connection`
interface.
+.. class:: VPNPlugin
+
+A class that can be used to query VPN plugins.
+
.. toctree::
:maxdepth: 2
The n-m utility
---------------
-n-m is a command-line tool to deal with network-manager. It can connect you to
-defined networks and disconnect you again.
-
-Usage: [options] action [arguments]
-
-Actions:
- list - List all defined and active connections
- activate - Activate a connection
- deactivate - Deactivate a connection
- offline - Deactivate all connections
- enable - Enable specific connection types
- disable - Disable specific connection types
- info - Information about a connection
+n-m is a command-line tool to interact with NetworkManager. With it, you can
+inspect various configuration items and (de-)activate connections.
+
+ Usage: [options] action [arguments]
+
+ Actions:
+ list - List all defined and active connections
+ activate - Activate a connection
+ deactivate - Deactivate a connection
+ offline - Deactivate all connections
+ enable - Enable specific connection types
+ disable - Disable specific connection types
+ info - Information about a connection
+ dump - Dump a python hash of connection information, suitable for
+ creating new connections
+
View
11 n-m
@@ -1,8 +1,11 @@
#!/usr/bin/python
-"""
-n-m is a command-line tool to deal with network-manager. It can connect you to
-defined networks and disconnect you again.
-"""
+#
+# Command-line tool to interact with NetworkManager. With this tool, you can
+# inspect various configuration items and (de-)activate connections.
+#
+# (C) 2011-2013 Dennis Kaarsemaker
+# License: GPL3+
+
from __future__ import print_function
usage = """%prog [options] action [arguments]
Please sign in to comment.
Something went wrong with that request. Please try again.