refactor naming, update documentation

radzhome · radzhome · commit 1b94b75bd7ae · 2016-01-15T22:49:30.000-05:00
diff --git a/fedex/__init__.py b/fedex/__init__.py
@@ -20,11 +20,11 @@
     
 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.
+python-fedex was created for use with various internal projects over the years.
+Not all services are implemented but only those 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.
+so that this module can be made more useful to others. Likewise, feel free to
+submit patches and service implementations as well if you would like to help.
 
 Getting Started
 ---------------
@@ -49,7 +49,7 @@
 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>}.
+our U{Github project<http://github.com/gtaylor/python-fedex/>} and enter
+an issue in the U{Issue Tracker<http://github.com/gtaylor/python-fedex/issues>}.
 """
-VERSION = __version__ = '2.1.0'
+VERSION = __version__ = '2.2.0'
diff --git a/fedex/config.py b/fedex/config.py
@@ -62,7 +62,7 @@ def __init__(self, key, password, account_number=None, meter_number=None, freigh
         self.integrator_id = integrator_id
         """@ivar: Web services integrator ID."""
         self.express_region_code = express_region_code
-        """@icar: Web services ExpressRegionCode"""
+        """@ivar: Web services ExpressRegionCode"""
         self.use_test_server = use_test_server
         """@ivar: When True, point to the test server."""
 
diff --git a/fedex/services/address_validation_service.py b/fedex/services/address_validation_service.py
@@ -1,6 +1,6 @@
 """
 Address Validation Service Module
-=================================
+
 This package contains the shipping methods defined by Fedex's 
 AddressValidationService WSDL file. Each is encapsulated in a class for 
 easy access. For more details on each, refer to the respective class's 
@@ -33,7 +33,6 @@ def __init__(self, config_obj, *args, **kwargs):
             'minor': '0'
         }
 
-        """@ivar: Holds the AddressValidationOptions WSDL object."""
         self.AddressesToValidate = []
         """@ivar: Holds the AddressToValidate WSDL object."""
         # Call the parent FedexBaseService class for basic setup work.
diff --git a/fedex/services/availability_commitment_service.py b/fedex/services/availability_commitment_service.py
@@ -1,6 +1,6 @@
 """
 Service Availability and Commitment Module
-=================================
+
 This package contains the shipping methods defined by Fedex's 
 ValidationAvailabilityAndCommitmentService WSDL file. Each is encapsulated in a class for
 easy access. For more details on each, refer to the respective class's 
@@ -31,21 +31,29 @@ def __init__(self, config_obj, *args, **kwargs):
             'minor': '0'
         }
 
-        """ivar: Carrier Code Default to Fedex (FDXE), or can bbe FDXG."""
         self.CarrierCode = None
+        """ivar: Carrier Code Default to Fedex (FDXE), or can bbe FDXG."""
+
+        self.Origin = None
+        """@ivar: Holds Origin Address WSDL object."""
+
+        self.Destination = None
+        """@ivar: Holds Destination Address WSDL object."""
 
-        """@ivar: Holds Addresses, Ship Date, Service and Packaging objects."""
-        self.Origin = self.Destination = None
         self.ShipDate = None
+        """@ivar: Ship Date date WSDL object."""
+
         self.Service = None
+        """@ivar: Service type, if set to None will get all available service information."""
+
         self.Packaging = None
+        """@ivar: Type of packaging to narrow down available shipping options or defaults to YOUR_PACKAGING."""
 
-        """@ivar: Holds the ValidationAvailabilityAndCommitmentService WSDL object."""
         # Call the parent FedexBaseService class for basic setup work.
         # Shortened the name of the wsdl, otherwise suds did not load it properly.
         # Suds throws the following error when using the long file name from FedEx:
         #
-        #   File "/Library/Python/2.7/site-packages/suds/wsdl.py", line 878, in resolve
+        # File "/Library/Python/2.7/site-packages/suds/wsdl.py", line 878, in resolve
         # raise Exception("binding '%s', not-found" % p.binding)
         # Exception: binding 'ns:ValidationAvailabilityAndCommitmentServiceSoapBinding', not-found
 
diff --git a/fedex/services/country_service.py b/fedex/services/country_service.py
@@ -1,6 +1,6 @@
 """
 Country Service Module
-=================================
+
 This package contains the shipping methods defined by Fedex's 
 CountryService WSDL file. Each is encapsulated in a class for
 easy access. For more details on each, refer to the respective class's 
@@ -13,7 +13,8 @@
 
 class FedexValidatePostalRequest(FedexBaseService):
     """
-    This class allows you validate service availability
+    This class allows you validate an address.
+    https://www.fedex.com/us/developer/WebHelp/ws/2015/html/WebServicesHelp/WSDVG/47_Country_Service.htm
     """
 
     def __init__(self, config_obj, *args, **kwargs):
@@ -31,18 +32,21 @@ def __init__(self, config_obj, *args, **kwargs):
             'minor': '0'
         }
 
-        """ivar: Carrier Code Default to Fedex (FDXE), or can bbe FDXG."""
         self.CarrierCode = None
+        """ivar: Carrier Code Default to Fedex (FDXE), or can bbe FDXG."""
 
-        """ivar: Routing Code Default to FDSD"""
         self.RoutingCode = None
+        """ivar: Routing Code Default to FDSD."""
 
-        """@ivar: Holds Addresses, Ship Date, Service and Packaging objects."""
         self.Address = None
+        """@ivar: Holds Address WSDL objects."""
+
         self.ShipDateTime = None
+        """@ivar: Holds the ShipDateTime date time objects."""
+
         self.CheckForMismatch = 1
+        """@ivar: Holds the CheckForMismatch boolean objects."""
 
-        """@ivar: Holds the ValidationAvailabilityAndCommitmentService WSDL object."""
         super(FedexValidatePostalRequest, self).__init__(
             self._config_obj, 'CountryService_v4.wsdl', *args, **kwargs)
 
diff --git a/fedex/services/package_movement.py b/fedex/services/package_movement.py
@@ -1,6 +1,6 @@
 """
 Package Movement Information Service
-====================================
+
 This package contains classes to check service availability, route, and postal
 codes. Defined by the PackageMovementInformationService WSDL file. 
 """
diff --git a/fedex/services/rate_service.py b/fedex/services/rate_service.py
@@ -1,6 +1,6 @@
 """
 Rate Service Module
-===================
+
 This package contains classes to request pre-ship rating information and to
 determine estimated or courtesy billing quotes. Time in Transit can be
 returned with the rates if it is specified in the request.
@@ -33,12 +33,12 @@ def __init__(self, config_obj, *args, **kwargs):
                               'intermediate': '0', 'minor': '0'}
 
         self.RequestedShipment = None
-        """@ivar: Holds the RequestedShipment WSDL object."""
+        """@ivar: Holds the RequestedShipment WSDL object including the shipper, recipient and shipt time."""
         # Call the parent FedexBaseService class for basic setup work.
-        super(FedexRateServiceRequest, self).__init__(self._config_obj,
-                                                      'RateService_v18.wsdl',
-                                                      *args, **kwargs)
+        super(FedexRateServiceRequest, self).__init__(
+            self._config_obj, 'RateService_v18.wsdl', *args, **kwargs)
         self.ClientDetail.Region = config_obj.express_region_code
+        """@ivar: Holds the express region code from the config object."""
 
     def _prepare_wsdl_objects(self):
         """
@@ -53,36 +53,34 @@ def _prepare_wsdl_objects(self):
         self.RequestedShipment = self.client.factory.create('RequestedShipment')
         self.RequestedShipment.ShipTimestamp = datetime.datetime.now()
 
-        TotalWeight = self.client.factory.create('Weight')
+        # Defaults for TotalWeight wsdl object.
+        total_weight = self.client.factory.create('Weight')
         # Start at nothing.
-        TotalWeight.Value = 0.0
+        total_weight.Value = 0.0
         # Default to pounds.
-        TotalWeight.Units = 'LB'
+        total_weight.Units = 'LB'
         # This is the total weight of the entire shipment. Shipments may
         # contain more than one package.
-        self.RequestedShipment.TotalWeight = TotalWeight
+        self.RequestedShipment.TotalWeight = total_weight
 
         # This is the top level data structure for Shipper information.
-        ShipperParty = self.client.factory.create('Party')
-        ShipperParty.Address = self.client.factory.create('Address')
-        ShipperParty.Contact = self.client.factory.create('Contact')
+        shipper = self.client.factory.create('Party')
+        shipper.Address = self.client.factory.create('Address')
+        shipper.Contact = self.client.factory.create('Contact')
 
         # Link the ShipperParty to our master data structure.
-        self.RequestedShipment.Shipper = ShipperParty
+        self.RequestedShipment.Shipper = shipper
 
         # This is the top level data structure for Recipient information.
-        RecipientParty = self.client.factory.create('Party')
-        RecipientParty.Contact = self.client.factory.create('Contact')
-        RecipientParty.Address = self.client.factory.create('Address')
-
+        recipient_party = self.client.factory.create('Party')
+        recipient_party.Contact = self.client.factory.create('Contact')
+        recipient_party.Address = self.client.factory.create('Address')
         # Link the RecipientParty object to our master data structure.
-        self.RequestedShipment.Recipient = RecipientParty
+        self.RequestedShipment.Recipient = recipient_party
 
-        Payor = self.client.factory.create('Payor')
-        # Grab the account number from the FedexConfig object by default.
-        Payor.AccountNumber = self._config_obj.account_number
-        # Assume US.
-        Payor.CountryCode = 'US'
+        # Make sender responsible for payment by default.
+        self.RequestedShipment.ShippingChargesPayment = self.create_wsdl_object_of_type('Payment')
+        self.RequestedShipment.ShippingChargesPayment.PaymentType = 'SENDER'
 
         # Start with no packages, user must add them.
         self.RequestedShipment.PackageCount = 0
diff --git a/fedex/services/ship_service.py b/fedex/services/ship_service.py
@@ -1,6 +1,6 @@
 """
 Ship Service Module
-===================
+
 This package contains the shipping 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.
@@ -51,43 +51,45 @@ def _prepare_wsdl_objects(self):
         self.RequestedShipment = self.client.factory.create('RequestedShipment')
         self.RequestedShipment.ShipTimestamp = datetime.datetime.now()
 
-        TotalWeight = self.client.factory.create('Weight')
+        # Defaults for TotalWeight wsdl object.
+        total_weight = self.client.factory.create('Weight')
         # Start at nothing.
-        TotalWeight.Value = 0.0
+        total_weight.Value = 0.0
         # Default to pounds.
-        TotalWeight.Units = 'LB'
+        total_weight.Units = 'LB'
         # This is the total weight of the entire shipment. Shipments may
         # contain more than one package.
-        self.RequestedShipment.TotalWeight = TotalWeight
+        self.RequestedShipment.TotalWeight = total_weight
 
-        # This is the top level data structure for Shipper information.
-        ShipperParty = self.client.factory.create('Party')
-        ShipperParty.Address = self.client.factory.create('Address')
-        ShipperParty.Contact = self.client.factory.create('Contact')
+        # This is the top level data structure Shipper Party information.
+        shipper_party = self.client.factory.create('Party')
+        shipper_party.Address = self.client.factory.create('Address')
+        shipper_party.Contact = self.client.factory.create('Contact')
 
-        # Link the ShipperParty to our master data structure.
-        self.RequestedShipment.Shipper = ShipperParty
+        # Link the Shipper Party to our master data structure.
+        self.RequestedShipment.Shipper = shipper_party
 
-        # This is the top level data structure for Recipient information.
-        RecipientParty = self.client.factory.create('Party')
-        RecipientParty.Contact = self.client.factory.create('Contact')
-        RecipientParty.Address = self.client.factory.create('Address')
+        # This is the top level data structure for RecipientParty information.
+        recipient_party = self.client.factory.create('Party')
+        recipient_party.Contact = self.client.factory.create('Contact')
+        recipient_party.Address = self.client.factory.create('Address')
 
         # Link the RecipientParty object to our master data structure.
-        self.RequestedShipment.Recipient = RecipientParty
+        self.RequestedShipment.Recipient = recipient_party
 
-        Payor = self.client.factory.create('Payor')
+        payor = self.client.factory.create('Payor')
         # Grab the account number from the FedexConfig object by default.
         # Assume US.
-        Payor.ResponsibleParty = self.client.factory.create('Party')
-        Payor.ResponsibleParty.Address = self.client.factory.create('Address')
-        Payor.ResponsibleParty.Address.CountryCode = 'US'
+        payor.ResponsibleParty = self.client.factory.create('Party')
+        payor.ResponsibleParty.Address = self.client.factory.create('Address')
+        payor.ResponsibleParty.Address.CountryCode = 'US'
 
-        ShippingChargesPayment = self.client.factory.create('Payment')
-        ShippingChargesPayment.Payor = Payor
-        ShippingChargesPayment.PaymentType = 'SENDER'
+        # ShippingChargesPayment WSDL object default values.
+        shipping_charges_payment = self.client.factory.create('Payment')
+        shipping_charges_payment.Payor = payor
+        shipping_charges_payment.PaymentType = 'SENDER'
+        self.RequestedShipment.ShippingChargesPayment = shipping_charges_payment
 
-        self.RequestedShipment.ShippingChargesPayment = ShippingChargesPayment
         self.RequestedShipment.LabelSpecification = self.client.factory.create('LabelSpecification')
 
         # NONE, PREFERRED or LIST
diff --git a/fedex/services/track_service.py b/fedex/services/track_service.py
@@ -1,6 +1,6 @@
 """
 Tracking Service Module
-=======================
+
 This package contains the shipment tracking methods defined by Fedex's 
 TrackService WSDL file. Each is encapsulated in a class for easy access. 
 For more details on each, refer to the respective class's documentation.
@@ -34,9 +34,6 @@ def __init__(self, config_obj, *args, **kwargs):
         
         @type config_obj: L{FedexConfig}
         @param config_obj: A valid FedexConfig object.
-        
-        @type tracking_number_unique_id: str
-        @param tracking_number_unique_id: Used to distinguish duplicate FedEx tracking numbers.
         """
 
         self._config_obj = config_obj
@@ -49,7 +46,11 @@ def __init__(self, config_obj, *args, **kwargs):
             'minor': '0'
         }
         self.SelectionDetails = None
-        """@ivar: Holds the TrackPackageIdentifier WSDL object."""
+        """@ivar: Holds the SelectionDetails WSDL object that includes tracking type and value."""
+
+        # Set Default as None. 'INCLUDE_DETAILED_SCANS' or None
+        self.ProcessingOptions = None
+        """@ivar: Holds the TrackRequestProcessingOptionType WSDL object that defaults no None."""
 
         # Call the parent FedexBaseService class for basic setup work.
         super(FedexTrackRequest, self).__init__(
@@ -67,15 +68,12 @@ def _prepare_wsdl_objects(self):
         # Default to Fedex
         self.SelectionDetails.CarrierCode = 'FDXE'
 
-        TrackPackageIdentifier = self.client.factory.create('TrackPackageIdentifier')
+        track_package_id = self.client.factory.create('TrackPackageIdentifier')
 
         # Default to tracking number.
-        TrackPackageIdentifier.Type = 'TRACKING_NUMBER_OR_DOORTAG'
-
-        self.SelectionDetails.PackageIdentifier = TrackPackageIdentifier
+        track_package_id.Type = 'TRACKING_NUMBER_OR_DOORTAG'
 
-        # Set Default as None. 'INCLUDE_DETAILED_SCANS' or None
-        self.TrackRequestProcessingOptionType = None
+        self.SelectionDetails.PackageIdentifier = track_package_id
 
     def _check_response_for_request_errors(self):
         """
@@ -107,4 +105,4 @@ def _assemble_and_send_request(self):
             TransactionDetail=self.TransactionDetail,
             Version=self.VersionId,
             SelectionDetails=self.SelectionDetails,
-            ProcessingOptions=self.TrackRequestProcessingOptionType)
+            ProcessingOptions=self.ProcessingOptions)
