Added final docstrings, and prepped for first release

pycrs/__init__.py

@@ -1,12 +1,153 @@
 """
-PyCRS
-Karim Bahgat, 2015
+# PyCRS
+
+PyCRS is a pure Python GIS package for reading, writing, and converting between various
+common coordinate reference system (CRS) string and data source formats. 
+
+
+## Introduction
+
+Python should have a standalone GIS library focused solely on coordinate reference system metadata.
+That is, a library focused on the various formats used to store and represent crs definitions, including
+OGC WKT, ESRI WKT, Proj4, and various short-codes defined by organizations like EPSG, ESRI, and SR-ORG.
+Correctly parsing and converting between these formats is essential in many types of GIS work.
+For instance when trying to use PyProj to transform coordinates from a non-proj4 crs format. Or
+when wanting to convert the crs from a GeoJSON file to a .prj file. Or when simply adding a crs definition
+to a file that was previously missing one. 
+
+When I created PyCRS, the only way to read and convert between crs formats was to use the extensive Python
+GDAL suite and its srs submodule, but the requirements of some applications might exclude the use of
+GDAL. There have also been some online websites/services, but these only allow partial lookups or
+one-way conversion from one format to another. I therefore hope that PyCRS will make it easier for
+lightweight applications to read a broader range of data files and correctly interpret and possibly transform
+their crs definitions. Written entirely in Python I also hope it will help clarify the differences
+between the various formats, and make it easier for more people to help keep it up-to-date and bug-free. 
+
+
+## Status
+
+Currently, the supported formats are OGC WKT (v1), ESRI WKT, Proj4, and any EPSG, ESRI, or SR-ORG code
+available from spatialreference.org. In the future I hope to add support for OGC URN identifier strings,
+and GeoTIFF file tags.
+
+The package is still in alpha version, so it will not perfectly parse or convert between all crs,
+and it is likely to have several (hopefully minor) differences from the results of other parsers like GDAL.
+In the source repository there is a tester.py script, which uses a barrage of commonly
+used crs as listed on http://www.remotesensing.org/geotiff/proj_list/. Currently, the overall success rate
+for loading as well as converting between the three main formats is 70-90%, and visual inspections of 
+rendering the world with each crs generally look correct. However, whether the converted crs strings
+are logically equivalent to each other from a mathematical standpoint is something that needs a more detailed
+quality check. 
+
+
+## Platforms
+
+So far only tested on Python version 2.x, but should also be compatible with 3.x. 
+
+
+## Dependencies
+
+Pure Python, no dependencies. 
+
+
+## Installing it
+
+PyCRS is installed with pip from the commandline:
+
+    pip install pycrs
+
+It also works to just place the "pycrs" package folder in an importable location like 
+"PythonXX/Lib/site-packages". 
+
+
+## Example Usage
+
+Begin by importing the pycrs module:
+
+    import pycrs
+
+### Reading
+
+The first point of action when dealing with a data source's crs is that you should be able to
+parse it correctly. In most situations this will mean reading the ESRI .prj file that accomponies
+a shapefile or some other file. PyCRS has a convenience function for doing that:
+
+    fromcrs = pycrs.loader.from_file("path/to/shapefilename.prj")
+
+The same function also supports reading the crs from GeoJSON files:
+
+    fromcrs = pycrs.loader.from_file("path/to/geojsonfile.json")
+
+If your crs is not defined in a file there are also functions for that. For instance if you know the url
+where the crs is defined you can do:
+
+    fromcrs = pycrs.loader.from_url("www.somesite.com/someproj")
+
+Or if you are provided with the actual string representation of the crs, given by a web service for
+instance, you can load it using the appropriate function from the parser module or let PyCRS autodetect
+and load the crs type for you:
+
+    fromcrs = pycrs.parser.from_unknown_text(somecrs_string)
+
+### Converting
+
+Once you have read the crs of the original data source, you may want to convert it to some other crs format.
+A common reason for wanting this for instance, is if you want to reproject the coordinates of your spatial
+data. In Python this is typically done with the PyProj module which only takes proj4 strings, so you would
+have to convert your datasource's crs to proj4:
+
+    fromcrs_proj4 = fromcrs.to_proj4()
+
+You can then use PyCRS to define your target projection in the string format of your choice, before converting
+it to the proj4 format that PyProj expects:
+
+    tocrs = pycrs.parser.from_esri_code(54030) # Robinson projection from esri code
+    tocrs_proj4 = tocrs.to_proj4()
+
+With the source and target projections defined in the proj4 crs format, you are ready to transform your
+data coordinates with PyProj, which is not covered here.
+
+### Writing
+
+After you transform your data coordinates you may also wish to save the data back to file along with the new
+crs. With PyCRS you can do this in a variety of crs format. For instance:
+
+    with open("shapefile.prj", "w") as writer:
+        writer.write(tocrs.to_esri_wkt())
+
+PyCRS also gives access to each crs element and parameter that make up a crs in the "elements" subpackage,
+so you could potentially also build a crs from scratch and then save it to a format of your choice.
+Inspect the parser submodule source code for inspiration on how to go about this. 
+
+
+## More Information:
+
+This tutorial only covered some basic examples. For the full list of functions and supported crs formats,
+check out the API Documentation. 
+
+- [Home Page](http://github.com/karimbahgat/PyCRS)
+- [API Documentation](http://pythonhosted.org/PyCRS)
+
+
+## License:
+
+This code is free to share, use, reuse,
+and modify according to the MIT license, see license.txt
+
+
+## Credits:
+
+Karim Bahgat (2015)
 
-Intro...
 """
 
+__version__ = "0.1.2"
+
 
 from . import loader
 from . import parser
 from . import utils
 
+
+
+

pycrs/elements/__init__.py

@@ -1,3 +1,7 @@
+"""
+Access to the various construct and parameter classes needed to build a CRS object.
+"""
+
 from . import datums
 from . import ellipsoids
 from . import projections

pycrs/loader.py

@@ -16,10 +16,13 @@ def from_url(url, format=None):
     Returns the crs object from a string interpreted as a specified format, located at a given url site.
 
     Arguments:
+
     - *url*: The url where the crs string is to be read from. 
-    - *format*: Which format to parse the crs string as. One of "ogc wkt", "esri wkt", or "proj4".
+    - *format* (optional): Which format to parse the crs string as. One of "ogc wkt", "esri wkt", or "proj4".
+        If None, tries to autodetect the format for you (default).
 
     Returns:
+
     - CRS object.
     """
     # first get string from url
@@ -41,6 +44,10 @@ def from_url(url, format=None):
 def from_file(filepath):
     """
     Returns the crs object from a file, with the format determined from the filename extension.
+
+    Arguments:
+
+    - *filepath*: filepath to be loaded, including extension. 
     """
     if filepath.endswith(".prj"):
         string = open(filepath, "r").read()

pycrs/parser.py

@@ -22,9 +22,11 @@ def from_epsg_code(code):
     Parses based on the proj4 representation.
 
     Arguments:
+
     - *code*: The EPSG code as an integer.
 
     Returns:
+
     - CRS object. 
     """
     # must go online (or look up local table) to get crs details
@@ -39,9 +41,11 @@ def from_esri_code(code):
     Parses based on the proj4 representation.
 
     Arguments:
+
     - *code*: The ESRI code as an integer.
 
     Returns:
+
     - CRS object.
     """
     # must go online (or look up local table) to get crs details
@@ -56,9 +60,11 @@ def from_sr_code(code):
     Parses based on the proj4 representation.
 
     Arguments:
+
     - *code*: The SR-ORG code as an integer.
 
     Returns:
+
     - CRS object.
     """
     # must go online (or look up local table) to get crs details
@@ -72,11 +78,13 @@ def from_ogc_wkt(string, strict=False):
     Parse crs as ogc wkt formatted string and return the resulting crs object.
 
     Arguments:
+
     - *string*: The OGC WKT representation as a string.
     - *strict* (optional): When True, the parser is strict about names having to match
         exactly with upper and lowercases. Default is not strict (False).
 
     Returns:
+
     - CRS object.
     """
     # parse arguments into components
@@ -88,11 +96,13 @@ def from_esri_wkt(string, strict=False):
     Parse crs as esri wkt formatted string and return the resulting crs object.
 
     Arguments:
+
     - *string*: The ESRI WKT representation as a string.
     - *strict* (optional): When True, the parser is strict about names having to match
         exactly with upper and lowercases. Default is not strict (False).
 
     Returns:
+
     - CRS object.
     """
     # parse arguments into components
@@ -104,6 +114,7 @@ def from_unknown_wkt(string, strict=False):
     Given an unknown wkt string, detect if uses ogc or esri flavor, and parse the crs accordingly.
 
     Arguments:
+
     - *string*: The unknown WKT representation as a string.
     - *strict* (optional): When True, the parser is strict about names having to match
         exactly with upper and lowercases. Default is not strict (False).
@@ -120,12 +131,14 @@ def _from_wkt(string, wkttype, strict=False):
     Internal method for parsing wkt, with minor differences depending on ogc or esri style.
 
     Arguments:
+
     - *string*: The OGC or ESRI WKT representation as a string.
     - *wkttype* (optional): How to parse the WKT string, as either 'ogc', 'esri', or None. If None, tries to autodetect the wkt type before parsing (default). 
     - *strict* (optional): When True, the parser is strict about names having to match
         exactly with upper and lowercases. Default is not strict (False).
 
     Returns:
+
     - CRS object.
     """
     # TODO
@@ -399,11 +412,13 @@ def from_proj4(string, strict=False):
     Parse crs as proj4 formatted string and return the resulting crs object.
 
     Arguments:
+
     - *string*: The proj4 representation as a string.
     - *strict* (optional): When True, the parser is strict about names having to match
         exactly with upper and lowercases. Default is not strict (False).
 
     Returns:
+
     - CRS object.
     """
     # parse arguments into components
@@ -713,11 +728,13 @@ def from_unknown_text(text, strict=False):
     Detect crs string format and parse into crs object with appropriate function.
 
     Arguments:
+
     - *string*: The crs text representation of unknown type. 
     - *strict* (optional): When True, the parser is strict about names having to match
         exactly with upper and lowercases. Default is not strict (False).
 
     Returns:
+
     - CRS object.
     """
 

pycrs/utils.py

@@ -12,6 +12,7 @@ def build_crs_table(savepath):
     NOTE: Might take a while.
 
     Arguments:
+
     - *savepath*: The absolute or relative filepath to which to save the crs table, including the ".txt" extension. 
     """
     # create table
@@ -70,11 +71,13 @@ def crscode_to_string(codetype, code, format):
     Lookup crscode on spatialreference.org and return in specified format.
 
     Arguments:
+
     - *codetype*: "epsg", "esri", or "sr-org".
     - *code*: The code.
     - *format*: The crs format of the returned string. One of "ogcwkt", "esriwkt", or "proj4", but also several others...
 
     Returns:
+
     - Crs string in the specified format. 
     """
     link = 'http://spatialreference.org/ref/%s/%s/%s/' %(codetype,code,format)