WARNING
=======

PyPI package not officially supported by Google. Uploaded by Nikhil Benesch (http://github.com/benesch). Google has expressed interest in maintaining an official PyPI release--track the progress here: https://code.google.com/p/google-api-ads-python/issues/detail?id=65

The "config.py" script referred to below and in documentation is installed globally as "dfp_config.py".

Direct library bugs to official Google maintainers: https://code.google.com/p/google-api-ads-python/

Direct packaging errors to me: nikhil.benesch@gmail.com

Google's DoubleClick for Publishers API Python Client Library
=============================================================

Google's DoubleClick for Publishers API service lets developers design computer
programs that interact directly with the DFP platform. With these applications,
advertisers and third parties can more efficiently -- and creatively -- manage
their large or complex DFP accounts.

Google's DFP API Python Client Library makes it easy to write
Python clients to programmatically access DFP accounts. One of
the main features of this client library is that it hides the SOAP layer from
end users, which makes it much easier to interact with API. The outgoing and
incoming SOAP messages are monitored and logged on demand. The response headers
like responseTime, requestId, etc. can also be logged on demand. Another nice
feature of this client library is that it handles data types for all API call
parameters. You no longer need to remember that Date.hour is of type int and
Company.id is of type long. Both of these variables can now be sent as simple
strings, when passing them as parameters. In fact, all variables are passed as
either dict, list, or str. The conversion to the right type is handled
internally by the client library.

Starting with 9.0.0 the client library uses a patched version of the SOAPpy
web services toolkit from http://pywebsvcs.sourceforge.net/, which is included
in the tarball download. This change allows us to write more consistent and
maintainable code, including unit tests and code examples.

This change also includes fixes to make SOAPpy follow the WSDL when returning
objects. For example, when an element is defined in the WSDL with maxOccurs > 1,
this is traditionally represented as a list (SOAPpy would return back a list of
elements when more than one element is present in the response). However, when
only a single element is returned in the response, SOAPpy used to return back
just the element, not the element wrapped in a list. Starting with 9.0.0, it
will correctly return back a list with a single element.

Two modules are supported for parsing SOAP XML messages. By default, the client
library uses the PyXML module in order to parse SOAP XML messages. In addition,
the library also supports ElementTree module, which may be activated simply by
setting the appropriate config value (i.e. config['xml_parser']). Note that if
you already have an lxml module installed and wish to use ElementTree, you do
not need to install ElementTree. The lxml module is mostly compatible with
ElementTree. The cElementTree module is now also supported. Note that when
ElementTree module is used and PrettyPrintXml is enabled, the logged XML is
slightly different from what gets sent over the wire.

Although there are projects out there that still support PyXML, it is no longer
maintained. The last update for the ElementTree library is dated 2007-09-12.
Out of these three libraries, the lxml is the one that was updated most
recently. Also, if you have Python v2.5+, the ElementTree comes with it.

The code examples, located in "examples/", demonstrate how to use client
library. For additional examples, take a look at the unit tests in "tests/".

Useful scripts are located in the "scripts/" directory.

The documentation was generated using Epydoc, a nice tool for generating API
documentation for Python modules, and is located in "docs/".

The client library includes a set of unit tests located in "tests/". Whenever
changes are made to the client library, the appropriate unit test should be
executed to make sure that everything is working as intended and no new bugs
were introduced.


How do I start?
---------------

If you haven't done so yet, you'll need to a DFP account with API access to
make requests. If you do not have a DFP account, you can follow the instructions
here:

  https://developers.google.com/doubleclick-publishers/docs/signup.html

If you do have a DFP account, you can enable API access by following the
instructions here:

  https://developers.google.com/doubleclick-publishers/docs/prod_signup

Step-by-step guide for accessing the test account:
-----------------------------------------

1) Make sure you have Python v2.4 or above installed. The latest stable version
   can be fetched from http://www.python.org/.

2) If using PyXML, fetch the latest version of the PyXML module from
   http://sourceforge.net/projects/pyxml/. This is required by the client
   library.

3) Sign up for a Google Account. In later steps, we'll assume that the new login
   is joe.shmoe@gmail.com.

4) Navigate to the directory that contains your downloaded unzipped client
   library and run the "setup.py" script to install the "adspygoogle.dfp"
   module.

   $ python setup.py build install

5) From the same directory, run the "config.py" script to set
   authentication headers. More information about the format of each header is
   at https://developers.google.com/doubleclick-publishers/docs/developers_guide#headers.
   Example,

   OAuth 2.0 client ID: xxxxxxxxxxxxxx
   OAuth 2.0 client secret: xxxxxxxxxxxxxx
   OAuth 2.0 refresh token: xxxxxxxxxxxxxx
   Network code: 123456
   Application name: GoogleTest

   Select XML parser [1=PyXML, 2=ElementTree]: 1
   Enable debugging mode [y/n]: n
   Enable SOAP XML logging mode [y/n]: y
   Enable API request logging mode [y/n]: y

7) Read over the documentation in "docs/index.html" to familiarize yourself with
   the API of the client library.


Where do I submit bug reports and/or feature requests?
---------------------------------------------------

Use the issue tracker at:
  http://code.google.com/p/google-api-ads-python/issues/list.

Make sure to subscribe to our Google Plus page for API change announcements and
other news:

  https://plus.google.com/+GoogleAdsDevelopers


External Dependencies:
----------------------

    - Python v2.4+         -- http://www.python.org/
    - PyXML v0.8.3+        -- http://sourceforge.net/projects/pyxml/
                           or
      ElementTree v1.2.6+  -- http://effbot.org/zone/element-index.htm
                           or
      cElementTree v1.0.6+ -- http://www.python.org/
                           (part of the Python v2.5+)
                           or
      lxml v2.2+           -- http://codespeak.net/lxml/index.html
    - Epydoc               -- http://epydoc.sourceforge.net/
                           (only if you will be generating docs)
    - fpconst              -- http://pypi.python.org/pypi/fpconst/#downloads
    - oauth2client         -- http://code.google.com/p/google-api-python-client/downloads/list
                           (only if using oauth2)
    - Google Account       -- https://www.google.com/accounts/NewAccount


Author:
    api.sgrinberg@gmail.com (Stan Grinberg)
    api.shamjeff@gmail.com (Jeff Sham)