Permalink
Browse files

Added installation instructions to help you get started. Resolves iss…

…ue 79.

git-svn-id: http://gdata-python-client.googlecode.com/svn/trunk@227 7ed92db3-4423-0410-a5bc-5f2579731264
  • Loading branch information...
1 parent e83903f commit ea64dced636d683e3cd7c20d6f745cd9a7431147 api.jscudder committed Dec 3, 2007
Showing with 248 additions and 0 deletions.
  1. +247 −0 INSTALL.txt
  2. +1 −0 MANIFEST
View
@@ -0,0 +1,247 @@
+To get started using the library, you need to make sure that the library
+and dependencies can be imported. Short instructions:
+
+sudo python setup.py install
+
+or
+
+python setup.py install --home=~
+and set your PYTHONPATH to include your home directory.
+
+Long instructions copied from the following article from Aug. 2007:
+
+Getting Started with the Google Data Python Library
+http://code.google.com/support/bin/answer.py?answer=75582
+
+==Introduction==
+
+So you've decided to use the Google data Python client library to write an
+application using one of the many Google data services. Excellent choice!
+My aim with this short tutorial is to quickly get you started in using the
+client library to develop your application.
+
+You probably want to jump in and start creating your application right
+away. First though, you may need to configure your development environment
+and set up the tools you'll need to run the modules included in the client
+library. Follow the steps below and you'll be running code in no time.
+
+==Installing Python==
+
+If you're going to be developing with the Python client library, you'll
+need a working version of Python 2.2 or higher. Many operating systems
+come with a version of Python included, so you may be able to skip the
+installation step. To see which version of Python you have, run
+python -V in a command line terminal. (Note: the V is uppercase.) This
+should result in something like:
+
+Python 2.4.3
+
+If you see version 2.2 or higher, then you can start installing dependencies.
+Otherwise, look below to find installation/upgrade instructions for your
+operating system.
+
+--Installing Python on Windows--
+
+There are quite a few implementations of Python to choose from in Windows,
+but for purposes of this guide, I'll be using the .msi installer found on
+python.org.
+
+ 1. Begin by downloading the installer from the Python download page.
+ http://www.python.org/download/
+ 2. Run the installer ? you can accept all the default settings
+ 3. To see if your install is working as expected, open a command prompt and
+ run python -V.
+
+--Installing Python on Mac OS X--
+
+The list of downloads on python.org has .dmg installers for the Mac users out
+there. Here are the steps to install one of them:
+
+ 1. Navigate to http://www.python.org/download/mac/
+ 2. From this page, download the installer for the appropriate version of
+ Mac OS X. Note: The Python installation page for Mac OS X 10.3.8 and
+ below is different than newer versions of Mac OS X. To find your OS X
+ version, choose About This Mac from the Apple menu in the top-left
+ corner of your screen.
+ 3. After the download finishes, double-click the new disk image file
+ (ex. python-2.5-macosx.dmg) to mount it. If you're running Safari, this
+ has already been done for you.
+ 4. Open the mounted image and double-click the installer package inside.
+ 5. Follow the installation instructions and read the information and
+ license agreements as they're presented to you. Again, the default
+ settings will work fine here.
+ 6. Verify the installation by opening Terminal.app
+ (in /Applications/Utilities) and running python -V. The installation's
+ version should appear.
+
+--Installing Python on Linux--
+
+To install on Linux and other *nix style operating systems, I prefer to
+download the source code and compile it. However, you may be able to use your
+favorite package manager to install Python. (For example, on Ubuntu this can
+be as easy as running sudo apt-get install python on the command line.) To
+install from source, follow these steps:
+
+ 1. Download the source tarball from the Python download page.
+ http://python.org/download/
+ 2. Once you've downloaded the package, unpack it using the command line.
+ You can use the following
+
+ tar zxvf Python-2.<Your version>.tgz
+
+ 3. Next, you'll need to compile and install the source code for the Python
+ interpreter. In the decompressed directory, run ./configure to generate
+ a makefile.
+ 4. Then, run make. This will create a working Python executable file in
+ the local directory. If you don't have root permission or you just want
+ to use Python from your home directory, you can stop here. You'll be
+ able to run Python from this directory, so you might want to add it to
+ your PATH environment variable.
+ 5. I prefer to have Python installed in /usr/bin/ where most Python
+ scripts look for the interpreter. If you have root access, then run
+ make install as root. This will install Python in the default location
+ and it will be usable by everyone on your machine.
+ 6. Check to see if your install is working as expected by opening a
+ terminal and running python -V.
+
+==Installing Dependencies==
+
+Currently, the only external dependency is an XML library named ElementTree.
+If you are using Python version 2.5 or higher, you won't need to install
+ElementTree since it comes with the Python package.
+
+To see if ElementTree is already present on your system, do the following:
+
+ 1. Run the Python interpreter. I usually do this by executing python on
+ the command line.
+ 2. Try importing the ElementTree module. If you are using Python 2.5 or
+ higher, enter the following in the interpreter:
+
+ from xml.etree import ElementTree
+
+ For older versions, enter:
+
+ from elementtree import ElementTree
+
+ 3. If the import fails, then you will need to continue reading this
+ section. If it works, then you can skip to Installing the Google
+ data library.
+ 4. Download a version which is appropriate for your operating system.
+ For example, if you are using Windows, download
+ elementtree-1.2.6-20050316.win32.exe. For other operating systems,
+ I recommend downloading a compressed version.
+ 5. If you are using a .tar.gz or .zip version of the library, first
+ unpack, then install it by running ./setup.py install.
+
+Running ./setup.py install attempts to compile the library and place it in
+the system directory for your Python modules. If you do not have root access,
+you can install the modules in your home directory or an alternate location by
+running ./setup.py install --home=~. This will place the code in your home
+directory.
+
+There is another option which avoids installing altogether. Once you
+decompress the download, you will find a directory named elementtree. This
+directory contains the modules which you will need to import. When you call
+import from within Python, it looks for a module with the desired name in
+several places. The first place it looks is in the current directory, so
+if you are always running your code from one directory, you could just put
+the elementtree directory there. Python will also look at the directories
+listed in your PYTHONPATH environment variable. For instructions on
+editing your PYTHONPATH, see the Appendix at the end of this article.
+I recommend using ./setup.py install for elementtree.
+
+==Installing the Google Data Library==
+
+Download the Google data Python library if you haven't done so. Look for the
+latest version on the Python project's downloads page.
+
+After downloading the library, unpack it using unzip or tar zxvf depending
+on the type of download you chose.
+
+Now you are ready to install the library modules so that they can be imported
+into Python. There are several ways you can do this:
+
+ * If you have the ability to install packages for all users to access,
+ you can run ./setup.py install from the unpacked archive's main
+ directory.
+ * If you want to install these modules for use in your home directory,
+ you can run ./setup.py install --home=<your home directory>.
+
+In some cases, you want to avoid installing the modules altogether. To do
+that, modify your PYTHONPATH environment variable to include a directory
+which contains the gdata and atom directories for the Google data Python
+client library. For instructions on modifying your PYTHONPATH, see the
+Appendix at the end of this article.
+
+ * One final option that I'll mention, is copying the gdata and atom
+ directories from the src directory into whatever directory you are
+ in when you execute python. Python will look in the current directory
+ when you do an import, but I don't recommend this method unless you
+ are creating something quick and simple.
+
+Once you've installed the Google data library, you're ready to take the
+library for a test drive.
+
+==Running Tests and Samples==
+
+The Google data Python client library distributions include some test cases
+which are used in the development of the library. They can also serve as a
+quick check to make sure that your dependencies and library installation are
+working. From the top level directory where you've unpacked your copy of the
+library, try running:
+
+./tests/run_data_tests.py
+
+If this script runs correctly, you should see output on the command line
+like this:
+
+Running all tests in module gdata_test
+.......
+----------------------------------------------------------------------
+Ran 7 tests in 0.025s
+
+OK
+
+Running all tests in module atom_test
+..........................................
+----------------------------------------------------------------------
+Ran 42 tests in 0.016s
+
+OK
+
+...
+
+If you did not see any errors as the tests execute, then you have probably set
+up your environment correctly. Congratulations!
+
+For further information see the original article:
+http://code.google.com/support/bin/answer.py?answer=75582
+
+==Appendix: Modifying the PYTHONPATH==
+
+When you import a package or module in Python, the interpreter looks for the
+file in a series of locations including all of the directories listed in the
+PYTHONPATH environment variable. I often modify my PYTHONPATH to point to
+modules where I have copied the source code for a library I am using. This
+prevents the need to install a module each time it is modified because
+Python will load the module directly from directory which contains the
+modified source code.
+
+I recommend the PYTHONPATH approach if you are making changes to the client
+library code, or if you do not have admin rights on your system. By editing
+the PYTHONPATH, you can put the required modules anywhere you like.
+
+I modified my PYTHONPATH on a *nix and Mac OS X system by setting it in my
+.bashrc shell configuration file. If you are using the bash shell, you can
+set the variable by adding the following line to your ~/.bashrc file.
+
+export PYTHONPATH=$PYTHONPATH:/home/<my_username>/svn/gdata-python-client/src
+
+You can then apply these changes to your current shell session by executing
+
+source ~/.bashrc.
+
+For Windows XP, pull up the Environment Variables for your profile:
+Control Panel > System Properties > Advanced > Environment Variables. From
+there, you can either create or edit the PYTHONPATH variable and add the
+location of your local library copy.
View
@@ -1,5 +1,6 @@
README.txt
RELEASE_NOTES.txt
+INSTALL.txt
MANIFEST
setup.py
src/atom/__init__.py

0 comments on commit ea64dce

Please sign in to comment.