Shipment creation is in and ready for refinement. It's in decent proof-of-concept shape, though.

Author: Greg Taylor

examples/create_shipment.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python
+"""
+This example shows how to ship shipments.
+"""
+import logging
+from fedex.services.ship_service import FedexProcessShipmentRequest
+from fedex.config import FedexConfig
+
+# Set this to the INFO level to see the response from Fedex printed in stdout.
+logging.basicConfig(level=logging.ERROR)
+
+# FedexConfig objects should generally only be instantiated once and re-used
+# amongst different queries. They hold static data like account number.
+config_obj = FedexConfig(key='ZyNQQFdcxUATOx9L',
+                         password='GtngmKzs4Dk4RYmrlAjrLykwi',
+                         account_number='510087780',
+                         meter_number='118501898',
+                         use_test_server=True)
+
+# This is the object that will be handling our tracking request.
+ship = FedexProcessShipmentRequest(config_obj)
+
+# This is very generalized, top-level information.
+# REGULAR_PICKUP, REQUEST_COURIER, DROP_BOX, BUSINESS_SERVICE_CENTER or STATION
+ship.RequestedShipment.DropoffType = 'REGULAR_PICKUP'
+
+# See page 355 in WS_ShipService.pdf for a full list. Here are the common ones:
+# STANDARD_OVERNIGHT, PRIORITY_OVERNIGHT, FEDEX_GROUND, FEDEX_EXPRESS_SAVER
+ship.RequestedShipment.ServiceType = 'PRIORITY_OVERNIGHT'
+
+# What kind of package this will be shipped in.
+# FEDEX_BOX, FEDEX_PAK, FEDEX_TUBE, YOUR_PACKAGING
+ship.RequestedShipment.PackagingType = 'FEDEX_PAK'
+
+# No idea what this is.
+# INDIVIDUAL_PACKAGES, PACKAGE_GROUPS, PACKAGE_SUMMARY 
+ship.RequestedShipment.PackageDetail = 'INDIVIDUAL_PACKAGES'
+
+# Shipper contact info.
+ship.ShipperContact.PersonName = 'Sender Name'
+ship.ShipperContact.CompanyName = 'Some Company'
+ship.ShipperContact.PhoneNumber = '9012638716'
+
+# Shipper address.
+ship.ShipperAddress.StreetLines = ['Address Line 1']
+ship.ShipperAddress.City = 'Herndon'
+ship.ShipperAddress.StateOrProvinceCode = 'VA'
+ship.ShipperAddress.PostalCode = '20171'
+ship.ShipperAddress.CountryCode = 'US'
+ship.ShipperAddress.Residential = True
+
+# Recipient contact info.
+ship.RecipientContact.PersonName = 'Recipient Name'
+ship.RecipientContact.CompanyName = 'Recipient Company'
+ship.RecipientContact.PhoneNumber = '9012637906'
+
+# Recipient address
+ship.RecipientAddress.StreetLines = ['Address Line 1']
+ship.RecipientAddress.City = 'Herndon'
+ship.RecipientAddress.StateOrProvinceCode = 'VA'
+ship.RecipientAddress.PostalCode = '20171'
+ship.RecipientAddress.CountryCode = 'US'
+# This is needed to ensure an accurate rate quote with the response.
+ship.RecipientAddress.Residential = True
+
+# RECIPIENT, SENDER or THIRD_PARTY
+ship.ShippingChargesPayment.PaymentType = 'SENDER' 
+
+# These are example label values. You'll want to adjust these to fit your
+# usage case.
+ship.LabelSpecification.LabelFormatType = 'COMMON2D'
+ship.LabelSpecification.ImageType = 'PNG'
+ship.LabelSpecification.LabelStockType = 'PAPER_7X4.75'
+
+package1_weight = ship.create_wsdl_object_of_type('Weight')
+# Weight, in pounds.
+package1_weight.Value = 1.0
+package1_weight.Units = "LB"
+
+package1 = ship.create_wsdl_object_of_type('RequestedPackageLineItem')
+package1.Weight = package1_weight
+#print package1
+
+ship.add_package(package1)
+
+# If you'd like to see some documentation on the ship service WSDL, un-comment
+# this line. (Spammy).
+#print ship.client
+
+# Un-comment this to see your complete, ready-to-send request as it stands
+# before it is actually sent. This is useful for seeing what values you can
+# change.
+#print ship.RequestedShipment
+
+# Fires off the request, sets the 'response' attribute on the object.
+ship.send_request()
+
+# This will show the reply to your shipment being sent. You can access the
+# attributes through the response attribute on the request object.
+print ship.response

examples/track_shipment.py

@@ -175,6 +175,12 @@ def _check_response_for_request_errors(self):
         """
         pass
 
+    def create_wsdl_object_of_type(self, type_name):
+        """
+        Creates and returns a WSDL object of the specified type.
+        """
+        return self.client.factory.create(type_name)
+
     def send_request(self):
         """
         Sends the assembled request on the child object.

fedex/base_service.py

@@ -8,7 +8,7 @@
 from datetime import datetime
 from .. base_service import FedexBaseService
 
-class FedexShipRequest(FedexBaseService):
+class FedexProcessShipmentRequest(FedexBaseService):
     """
     This class allows you to track shipments by providing a tracking
     number or other identifying features. By default, you
@@ -17,128 +17,100 @@ class FedexShipRequest(FedexBaseService):
     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):
+    def __init__(self, config_obj, *args, **kwargs):
         """
         Sends a shipment tracking request. The optional keyword args
         detailed on L{FedexBaseService} apply here as well.
-        
-        @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.
+
+        @type config_obj: L{FedexConfig}
+        @param config_obj: A valid FedexConfig object.        
         """
         self._config_obj = config_obj
 
         # Holds version info for the VersionId SOAP object.
         self._version_info = {'service_id': 'ship', 'major': '7', 
                              'intermediate': '0', 'minor': '0'}
         # Call the parent FedexBaseService class for basic setup work.
-        super(FedexShipRequest, self).__init__(self._config_obj, 
-                                                'ShipService_v7.wsdl',
-                                                *args, **kwargs)
+        super(FedexProcessShipmentRequest, self).__init__(self._config_obj, 
+                                                         'ShipService_v7.wsdl',
+                                                         *args, **kwargs)
+        # Prepare the data structures.
+        self.__set_requested_shipment()
 
     def __set_requested_shipment(self):
         """
         This is the data that will be used to create your shipment. Create
         the data structure and get it ready for the WSDL request.
         """
-        RequestedShipment = self.client.factory.create('RequestedShipment')
-        RequestedShipment.ShipTimestamp = '2009-09-17T09:35:36-04:00'
-        RequestedShipment.DropoffType = 'REGULAR_PICKUP' # REGULAR_PICKUP, REQUEST_COURIER, DROP_BOX, BUSINESS_SERVICE_CENTER and STATION
-        RequestedShipment.ServiceType = 'PRIORITY_OVERNIGHT' # valid values STANDARD_OVERNIGHT, PRIORITY_OVERNIGHT, FEDEX_GROUND
-        RequestedShipment.PackagingType = 'FEDEX_PAK' # valid values FEDEX_BOX, FEDEX_PAK, FEDEX_TUBE, YOUR_PACKAGING
+        # This is the primary data structure for processShipment requests.
+        self.RequestedShipment = self.client.factory.create('RequestedShipment')
+        self.RequestedShipment.ShipTimestamp = datetime.now()
 
-        Weight = self.client.factory.create('Weight')
-        Weight.Value = 1.0
-        Weight.Units = 'LB' # LB or KG
-        # Assemble
-        RequestedShipment.TotalWeight = Weight
+        self.Weight = self.client.factory.create('Weight')
+        # Start at nothing.
+        self.Weight.Value = 0.0
+        # Default to pounds.
+        self.Weight.Units = 'LB'
+        # This is the total weight of the entire shipment. Shipments may
+        # contain more than one package.
+        self.RequestedShipment.TotalWeight = self.Weight
 
         """
         Begin shipper info.
         """
-        ShipperParty = self.client.factory.create('Party')
-        ShipperContact = self.client.factory.create('Contact')
-        ShipperContact.PersonName = 'Sender Name'
-        ShipperContact.CompanyName = 'Some Company'
-        ShipperContact.PhoneNumber = '9012638716'
-        # Assemble
-        ShipperParty.Contact = ShipperContact
-        
-        ShipperAddress = self.client.factory.create('Address')
-        ShipperAddress.StreetLines = ['Address Line 1']
-        ShipperAddress.City = 'Herndon'
-        ShipperAddress.StateOrProvinceCode = 'VA'
-        ShipperAddress.PostalCode = '20171'
-        ShipperAddress.CountryCode = 'US'
-        ShipperAddress.Residential = True
-        # Assemble
-        ShipperParty.Address = ShipperAddress
-        # Assemble
-        RequestedShipment.Shipper = ShipperParty
+        self.ShipperContact = self.client.factory.create('Contact')
+        self.ShipperAddress = self.client.factory.create('Address')
+        
+        # This is the top level data structure for Shipper information.
+        self.ShipperParty = self.client.factory.create('Party')
+        self.ShipperParty.Address = self.ShipperAddress
+        self.ShipperParty.Contact = self.ShipperContact
+        
+        # Link the ShipperParty to our master data structure.
+        self.RequestedShipment.Shipper = self.ShipperParty
         """
         End shipper info.
         """
 
         """
         Begin recipient info.
         """
-        RecipientParty = self.client.factory.create('Party')
-        RecipientContact = self.client.factory.create('Contact')
-        RecipientContact.PersonName = 'Recipient Name'
-        RecipientContact.CompanyName = 'Recipient Company'
-        RecipientContact.PhoneNumber = '9012637906'
-        # Assemble
-        RecipientParty.Contact = RecipientContact
-        
-        RecipientAddress = self.client.factory.create('Address')
-        RecipientAddress.StreetLines = ['Address Line 1']
-        RecipientAddress.City = 'Herndon'
-        RecipientAddress.StateOrProvinceCode = 'VA'
-        RecipientAddress.PostalCode = '20171'
-        RecipientAddress.CountryCode = 'US'
-        RecipientAddress.Residential = True
-        # Assemble
-        RecipientParty.Address = RecipientAddress
-        # Assemble
-        RequestedShipment.Recipient = RecipientParty
+        self.RecipientContact = self.client.factory.create('Contact')
+        self.RecipientAddress = self.client.factory.create('Address')
+        
+        # This is the top level data structure for Recipient information.
+        self.RecipientParty = self.client.factory.create('Party')
+        self.RecipientParty.Contact = self.RecipientContact
+        self.RecipientParty.Address = self.RecipientAddress
+        
+        # Link the RecipientParty object to our master data structure.
+        self.RequestedShipment.Recipient = self.RecipientParty
         """
         End recipient info.
         """
+                
+        self.Payor = self.client.factory.create('Payor')
+        # Grab the account number from the FedexConfig object by default.
+        self.Payor.AccountNumber = self._config_obj.account_number
+        # Assume US.
+        self.Payor.CountryCode = 'US'
 
-        ShippingChargesPayment = self.client.factory.create('Payment')
-        ShippingChargesPayment.PaymentType = 'SENDER' # RECIPIENT, SENDER and THIRD_PARTY
-        Payor = self.client.factory.create('Payor')
-        Payor.AccountNumber = self._config_obj.account_number
-        Payor.CountryCode = 'US'
-        ShippingChargesPayment.Payor = Payor
-        # Assemble
-        RequestedShipment.ShippingChargesPayment = ShippingChargesPayment
-        
-        LabelSpecification = self.client.factory.create('LabelSpecification')
-        LabelSpecification.LabelFormatType = 'COMMON2D'
-        LabelSpecification.ImageType = 'PNG'
-        LabelSpecification.LabelStockType = 'PAPER_7X4.75'
-        RequestedShipment.LabelSpecification = LabelSpecification
+        self.ShippingChargesPayment = self.client.factory.create('Payment')
+        self.ShippingChargesPayment.Payor = self.Payor
+        self.RequestedShipment.ShippingChargesPayment = self.ShippingChargesPayment
 
-        RequestedShipment.RateRequestTypes = ['ACCOUNT'] # ACCOUNT and LIST
-        RequestedShipment.PackageCount = 1
-        RequestedShipment.PackageDetail = 'INDIVIDUAL_PACKAGES'
+        self.LabelSpecification = self.client.factory.create('LabelSpecification')
+        self.RequestedShipment.LabelSpecification = self.LabelSpecification
 
-        # One package
-        RequestedPackageLineItem = self.client.factory.create('RequestedPackageLineItem')
-        RequestedPackageLineItem.Weight = Weight
+        self.RequestedShipment.RateRequestTypes = ['ACCOUNT'] # ACCOUNT and LIST
 
-        RequestedShipment.RequestedPackageLineItems = [RequestedPackageLineItem]
+        # Start with no packages, user must add them.
+        self.RequestedShipment.PackageCount = 0
+        self.RequestedShipment.RequestedPackageLineItems = []
 
-        self.logger.info(RequestedShipment)
-        self.RequestedShipment = RequestedShipment
+        # This is good to review if you'd like to see what the data structure
+        # looks like.
+        self.logger.info(self.RequestedShipment)
 
     def _assemble_and_send_request(self):
         """
@@ -147,19 +119,25 @@ def _assemble_and_send_request(self):
         @warning: NEVER CALL THIS METHOD DIRECTLY. CALL send_request(), WHICH RESIDES
             ON FedexBaseService AND IS INHERITED.
         """
-        self.__set_requested_shipment()
-        client = self.client
         # Fire off the query.
-        response = client.service.processShipment(WebAuthenticationDetail=self.WebAuthenticationDetail,
+        response = self.client.service.processShipment(WebAuthenticationDetail=self.WebAuthenticationDetail,
                                         ClientDetail=self.ClientDetail,
                                         TransactionDetail=self.TransactionDetail,
                                         Version=self.VersionId,
                                         RequestedShipment=self.RequestedShipment)
+        return response
+    
+    def add_package(self, package_item):
         """
-        processShipment(WebAuthenticationDetail WebAuthenticationDetail, 
-                        ClientDetail ClientDetail, 
-                        TransactionDetail TransactionDetail, 
-                        VersionId Version, 
-                        RequestedShipment RequestedShipment)
-        """
-        return response
+        Adds a package to the ship request.
+        
+        @type package_item: L{RequestedPackageLineItem}
+        @keyword package_item: A L{RequestedPackageLineItem}, created by
+            calling create_wsdl_object_of_type('RequestedPackageLineItem') on
+            this ShipmentRequest object. See examples/create_shipment.py for
+            more details.
+        """
+        self.RequestedShipment.RequestedPackageLineItems.append(package_item)
+        package_weight = package_item.Weight.Value
+        self.RequestedShipment.TotalWeight.Value += package_weight
+        self.RequestedShipment.PackageCount += 1

fedex/services/ship_service.py

@@ -30,6 +30,8 @@ def __init__(self, config_obj, tracking_value,
         Sends a shipment tracking request. The optional keyword args
         detailed on L{FedexBaseService} apply here as well.
         
+        @type config_obj: L{FedexConfig}
+        @param config_obj: A valid FedexConfig object.
         @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