Documentation rework

seveas · seveas · commit 9fc5872618ed · 2013-03-13T22:54:49.000+01:00
diff --git a/HACKING b/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
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -2,3 +2,4 @@ include docs/index.rst
 include docs/Makefile
 include docs/conf.py
 include examples/*
+include COPYING
diff --git a/NetworkManager.py b/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):
diff --git a/README b/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
 ==========================
 
diff --git a/docs/conf.py b/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.
diff --git a/docs/index.rst b/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,20 +24,33 @@ 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
 
 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
+
diff --git a/n-m b/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]
