Package: upoints
WarningAt this pointupointsonly exists to assist the users who have been using
it for years, Iabsolutelydonotrecommend its use to new users.Introductionupointsis a collection ofGPL v3licensed modules for working with
points on Earth, or other near spherical objects.  It allows you to calculate
the distance and bearings between points, manglexearth/xplanetdata files,
work with online UK trigpoint databases,NOAA’s weather station database and
other such location databases.Previous versions ofupointswere calledearth_distance, but the name
was changed as it no longer reflected the majority of uses the packages was
targeted at.Requirementsupoints’s only strict requirements beyond thePythonstandard library areaaarghandlxml, and as such should run with Python 2.6 or newer[1].  Ifupointsdoesn’t work with the version of Python you have installed, drop me
amailand I’ll endeavour to fix it.The modules have been tested on many UNIX-like systems, including Linux and OS
X, but it should work fine on other systems too.  The modules and scripts
contain a large collection of tests that can be checked withnose2.[1]If you still use Python v2.5 only small changes are required, for example
to the property definitions.[2]Some tests may fail due to rounding errors depending on the system the
tests are being run on, but such instances should be obvious even to the
casual user and some effort has been put in to reduce the likelihood of
such failures.ExampleThe simplest way to show howupointsworks is by example, and here goes:>>> from upoints import point
>>> Home = point.Point(52.015, -0.221)
>>> Telford = point.Point(52.6333, -2.5000)
>>> print("%d kM, with an initial bearing of %d°"
...       % (Home.distance(Telford), Home.bearing(Telford)))
169 kM, with an initial bearing of 294°All the class definitions, methods and independent functions contain hopefully
useful usage examples in the docstrings.  The API documentation is built withSphinx, and is available indoc/html/api/.There is some accompanying text and examples forpoint.py, formerlyedist.py, available ingeolocation and path cross.  More examples are
available forxearth.pyinxearth and path cross.  Some background and
more examples fortrigpoints.pyis online inTrigpointing and point.py.
Usage examples forcities.pyis available inCities and cities.py.  And
finally,Pythons on a planecontains information onweather_stations.py.ThanksThe following people have submitted patches, testing and feedback:Cédric Dufour -edist.py’s CSV import, and flight plan outputThomas Traber - GPX support enhancements, Points filtering, and some cool
usage scenariosKelly Turner -Xearthimport idea, and copious testingSimon Woods - TestingAPI StabilityAPI stability isn’t guaranteed across versions, although frivolous changes won’t
be made.Whenupoints1.0 is released the API will be frozen, and any changes which
aren’t backwards compatible will force a major version bump.LimitationsThe modules assume the caller will take care of significant digits, and output
formatting[2].  All results are returned with whatever precision your Python
install or system generates; unintuitive float representation, rounding errors,
warts and all.The reasoning is simple, the caller should always know what is required and any
heuristics added to the code would be just that – guesses, which can and will
be wrong.Theupointsmodules do not take flattening in to account, as in calculations
based in most populated areas of the earth the errors introduced by ignoring the
earth’s flattening are quite small.  Future versions may change if the
limitation becomes an issue in real use.Although not really a limitation one should also be careful to use data sources
that are based around the same datum, and even within two data sources that use
the same datum you should make sure they use the same representations.  It isn’t
unusual to find data sources from the USA that specify longitudes west of
Greenwich as positive for example.[3]A future release may include more standard output definitions, but there
is no intention to add “magic” data mangling.BugsIf you find a bug don’t hesitate to drop me amailpreferably including
a minimal testcase, or even better a patch!