Lots of documentation and fine-tuning.

Author: Greg Taylor

docs/build_docs.sh

@@ -0,0 +1 @@
+epydoc-2.6 -v --config epydoc.config --check

docs/epydoc.config

@@ -0,0 +1,19 @@
+[epydoc] # Epydoc section marker (required by ConfigParser)
+
+# Information about the project.
+name: python-fedex
+url: http://code.google.com/p/python-fedex/
+
+# The list of modules to document.  Modules can be named using
+# dotted names, module filenames, or package directory names.
+# This option may be repeated.
+modules: ../fedex
+
+# Write html output to the directory "apidocs"
+output: html
+target: apidocs/
+
+# Include all automatically generated graphs.  These graphs are
+# generated using Graphviz dot.
+graph: all
+dotpath: /opt/local/bin/dot

fedex/__init__.py

@@ -0,0 +1,34 @@
+"""
+python-fedex API Documentation
+==============================
+The python-fedex module is a light wrapper around Fedex's Web Services SOAP API.
+Using the excellent U{suds<https://fedorahosted.org/suds/>} SOAP client,
+the Fedex requests and responses are trivial to work with.
+
+What python-fedex is
+--------------------
+    - A light wrapper around Fedex Web Services SOAP API.
+    - Simple and easy to use.
+    - Minimal by design.
+
+What python-fedex is not
+------------------------
+    - An abstraction layer. python-fedex only assembles the needed SOAP calls
+        and returns a SOAP response through suds. This is easy enough to work with
+        that no abstraction is needed. Doing so would limit your use of the data.
+    - Anything more than a light wrapper.
+    
+A note on completeness
+----------------------
+python-fedex was created for use with some of my internal projects. For the
+initial release, only the things that I needed at the time were implemented.
+If there is missing functionality, please report an U{issue<http://code.google.com/p/python-fedex/issues/list>}
+so that I may make this module more useful to others. Likewise, feel free to
+submit patches as well if you would like to help.
+    
+Getting Support
+---------------
+If you have any questions, problems, ideas, or patch submissions, please visit
+our U{Google Code project<http://code.google.com/p/python-fedex/>} and enter
+an issue in the U{Issue Tracker<http://code.google.com/p/python-fedex/issues/list>}.
+"""

fedex/base_service.py

@@ -1,22 +1,64 @@
+"""
+The L{base_service} module contains classes that form the low level foundations
+of the Web Service API. Things that many different kinds of requests have in
+common may be found here.
+
+In particular, the L{FedexBaseService} class handles most of the basic,
+repetetive setup work that most requests do.
+"""
 import os
 import logging
 from suds.client import Client
 
 class FedexBaseService(object):
+    """
+    This class is the master class for all Fedex request objects. It gets all
+    of the common SOAP objects created via suds and populates them with
+    values from a L{FedexConfig} object, along with keyword arguments
+    via L{__init__}.
+    
+    @note: This object should never be used directly, use one of the included
+        sub-classes.
+    """
     def __init__(self, config_obj, wsdl_name, *args, **kwargs):
+        """
+        This constructor should only be called by children of the class. As is
+        such, only the optional keyword arguments caught by C{**kwargs} will
+        be documented.
+        
+        @type customer_transaction_id: L{str}
+        @keyword customer_transaction_id: A user-specified identifier to
+            differentiate this transaction from others. This value will be
+            returned with the response from Fedex.
+        @type carrier_code: L{str}
+        @keyword carrier_code: The carrier code to use for this query. In most
+            cases, this will be FDXE (Fedex Express). Must be one of the
+            following four-letter codes:
+                - FDXC (Fedex Cargo)
+                - FDXE (Fedex Express)
+                - FDXG (Fedex Ground)
+                - FXCC (Fedex Custom Critical)
+                - FXFR (Fedex Freight)
+                - FXSP (Fedex Smartpost)
+        """
         self.config_obj = config_obj
         self.wsdl_path = os.path.join(config_obj.wsdl_path, wsdl_name)
         self.client = Client('file://%s' % self.wsdl_path)
         self.logger = logging.getLogger('fedex')
+        self.response = None
+        """@ivar: The response from Fedex. You will want to pick what you
+            want out here here. This object does have a __str__() method,
+            you'll want to print or log it to see what possible values
+            you can pull."""
 
         self.logger.debug(self.client)
-        self.set_web_authentication_detail()
-        self.set_client_detail()
-        self.set_version_id()
-        self.set_carrier_code_type(*args, **kwargs)
-        self.set_transaction_detail(*args, **kwargs)
+        self.__set_web_authentication_detail()
+        self.__set_client_detail()
+        self.__set_version_id()
+        self.__set_carrier_code_type(*args, **kwargs)
+        self.__set_transaction_detail(*args, **kwargs)
 
-    def set_web_authentication_detail(self):
+    def __set_web_authentication_detail(self):
         """
         Sets up the WebAuthenticationDetail node. This is required for all
         requests.
@@ -32,7 +74,7 @@ def set_web_authentication_detail(self):
         self.logger.debug(WebAuthenticationDetail)
         self.WebAuthenticationDetail = WebAuthenticationDetail
 
-    def set_client_detail(self):
+    def __set_client_detail(self):
         """
         Sets up the ClientDetail node, which is required for all shipping
         related requests.
@@ -44,7 +86,7 @@ def set_client_detail(self):
         self.logger.debug(ClientDetail)
         self.ClientDetail = ClientDetail
 
-    def set_transaction_detail(self, *args, **kwargs):
+    def __set_transaction_detail(self, *args, **kwargs):
         """
         Checks kwargs for 'customer_transaction_id' and sets it if present.
         """
@@ -57,7 +99,7 @@ def set_transaction_detail(self, *args, **kwargs):
         else:
             self.TransactionDetail = None
 
-    def set_carrier_code_type(self, *args, **kwargs):
+    def __set_carrier_code_type(self, *args, **kwargs):
         """
         Checks kwargs for 'carrier_code' and sets it if present. 
         """
@@ -70,22 +112,22 @@ def set_carrier_code_type(self, *args, **kwargs):
         else:
             self.CarrierCodeType = None
 
-    def set_version_id(self):
+    def __set_version_id(self):
         """
         Pulles the versioning info for the request from the child request.
         """
         VersionId = self.client.factory.create('VersionId')
-        VersionId.ServiceId = self.version_info['service_id']
-        VersionId.Major = self.version_info['major']
-        VersionId.Intermediate = self.version_info['intermediate']
-        VersionId.Minor = self.version_info['minor']
+        VersionId.ServiceId = self._version_info['service_id']
+        VersionId.Major = self._version_info['major']
+        VersionId.Intermediate = self._version_info['intermediate']
+        VersionId.Minor = self._version_info['minor']
         self.logger.debug(VersionId)
         self.VersionId = VersionId
 
     def send_request(self):
         """
         Sends the assembled request on the child object.
         """
-        self.response = self.assemble_and_send_request()
+        self.response = self._assemble_and_send_request()
         self.logger.info("== FEDEX QUERY RESULT ==")
         self.logger.info(self.response)

fedex/config.py

@@ -1,17 +1,55 @@
+"""
+The L{config} module contains the L{FedexConfig} class, which is passed to
+the Fedex API calls. It stores useful information such as your Web Services
+account numbers and keys.
+
+It is strongly suggested that you create a single L{FedexConfig} object in
+your project and pass that to the various API calls, rather than create new
+L{FedexConfig} objects haphazardly. This is merely a design suggestion,
+treat it as such.
+"""
 import os
 import sys
 
 class FedexConfig(object):
     """
     Base configuration class that is used for the different Fedex SOAP calls.
+    These are generally passed to the Fedex request classes as arguments.
+    You may instantiate a L{FedexConfig} object with the minimal C{key} and
+    C{password} arguments and set the instance variables documented below
+    at a later time if you must.
     """
     def __init__(self, key, password, account_number=None, meter_number=None,
                  integrator_id=None, wsdl_path=None):
+        """
+        @type key: L{str}
+        @param key: Developer test key.
+        @type password: L{str}
+        @param password: The Fedex-generated password for your Web Systems
+            account. This is generally emailed to you after registration.
+        @type account_number: L{str}
+        @keyword account_number: The account number sent to you by Fedex after
+            registering for Web Services.
+        @type meter_number: L{str}
+        @keyword meter_number: The meter number sent to you by Fedex after
+            registering for Web Services.
+        @type integrator_id: L{str}
+        @keyword integrator_id: The integrator string sent to you by Fedex after
+            registering for Web Services.
+        @type wsdl_path: L{str}
+        @keyword wsdl_path: In the event that you want to override the path to
+            your WSDL directory, do so with this argument.
+        """
         self.key = key
+        """@ivar: Developer test key."""
         self.password = password
+        """@ivar: Fedex Web Services password."""
         self.account_number = account_number
+        """@ivar: Web Services account number."""
         self.meter_number = meter_number
+        """@ivar: Web services meter number."""
         self.integrator_id = integrator_id
+        """@ivar: Web services integrator ID."""
 
         # Allow overriding of the WDSL path.
         if wsdl_path == None:

fedex/services/__init__.py

@@ -0,0 +1,5 @@
+"""
+This module contains the wrappers around Fedex Web Service requests which you
+will want to instantiate and use with a L{FedexConfig} object supplying
+your static details. Each module here corresponds to a Fedex WSDL.
+"""

fedex/services/ship_service.py

@@ -1,33 +1,56 @@
+"""
+Ship Service Module
+===================
+This package contains the shipping and tracking methods defined by Fedex's 
+ShipService WSDL file. Each is encapsulated in a class for easy access. 
+For more details on each, refer to the respective class's documentation.
+"""
 from .. base_service import FedexBaseService
 
 class FedexTrackRequest(FedexBaseService):
+    """
+    This class allows you to track shipments by providing a tracking
+    number or other identifying features. By default, you
+    can simply pass a tracking number to the constructor. If you would like
+    to query shipments based on something other than tracking number, you will
+    want to read the documentation for the L{__init__} method. 
+    Particularly, the tracking_value and package_identifier arguments.
+    """
     def __init__(self, config_obj, tracking_value,
                  package_identifier='TRACKING_NUMBER_OR_DOORTAG',
                  *args, **kwargs):
         """
-        Sends a shipment tracking request.
+        Sends a shipment tracking request. The optional keyword args
+        detailed on L{FedexBaseService} apply here as well.
         
-        package_identifier: (str) Determines what you are using to query for
-                                  the shipment. The default assumes that
-                                  tracking_value will be a Fedex tracking #.
-        tracking_value: (str) Based on the value of package_identifier, this
-                              will be anything from a tracking number to 
-                              a purchase order number.
+        @type  tracking_value: L{str} 
+        @param tracking_value: Based on the value of package_identifier, 
+            this will be anything from a tracking number to a purchase order 
+            number.
+        @type    package_identifier: L{str}
+        @keyword package_identifier: Determines what you are using to query for
+            the shipment. The default assumes that tracking_value will be a Fedex 
+            tracking number.
         """
-        self.config_obj = config_obj
+        self._config_obj = config_obj
+        
         # Holds version info for the VersionId SOAP object.
-        self.version_info = {'service_id': 'trck', 'major': '4', 
+        self._version_info = {'service_id': 'trck', 'major': '4', 
                              'intermediate': '0', 'minor': '0'}
         # Call the parent FedexBaseService class for basic setup work.
-        super(FedexTrackRequest, self).__init__(config_obj, 
+        super(FedexTrackRequest, self).__init__(self._config_obj, 
                                                 'TrackService_v4.wsdl',
                                                 *args, **kwargs)
-        # Start preparing the Fedex-specific things.
-        self.tracking_value = tracking_value
+
+        # Important request-specific instance variables.
         self.package_identifier = package_identifier
-        self.set_track_package_identifier()
+        """@ivar: Determines what L{tracking_value} is, be it a tracking number,
+            purchase order, or other things."""
+        self.tracking_value = tracking_value
+        """@ivar: This is typically a Fedex tracking number, but setting 
+            L{package_identifier} to other values makes this change."""
 
-    def set_track_package_identifier(self):
+    def __set_track_package_identifier(self):
         """
         This sets the package identifier information. This may be a tracking
         number or a few different things as per the Fedex spec.
@@ -38,12 +61,14 @@ def set_track_package_identifier(self):
         self.logger.debug(TrackPackageIdentifier)
         self.TrackPackageIdentifier = TrackPackageIdentifier
 
-    def assemble_and_send_request(self):
+    def _assemble_and_send_request(self):
         """
         Fires off the Fedex request.
-        NEVER CALL THIS METHOD DIRECTLY. CALL SEND_REQUEST(), WHICH RESIDES
-        ON FedexBaseService AND IS INHERITED.
+        
+        @warning: NEVER CALL THIS METHOD DIRECTLY. CALL send_request(), WHICH RESIDES
+            ON FedexBaseService AND IS INHERITED.
         """
+        self.__set_track_package_identifier()
         client = self.client
         # Fire off the query.
         response = client.service.track(WebAuthenticationDetail=self.WebAuthenticationDetail,