Geocoder to geocoder3 migration
During initial migration of geocoder project to geocoder3 many changes in structure and approach was made. Here is list of noticeable changes, that should be considered during migration from geocoder to geocoder3. Also, please read changes in described in project releases section.
Some parts of text below describe new provider’s approach. This is valid only to providers, that are marked as Geocoder3 ready in main readme.md file.
Default geocoding engine changed from Google to OpenStreetMap
As Google engine now requires mandatory API key, default engine changed to free OpenStreetMap.
Some helper functions removed from api.py
and project
Functions for ‘silence’ geocoding or IP geocoding are removed from project. Please
use exact provider and provider configuration for such requests. Functions itself
located in api.py
.
List of removed functions:
geocoder.elevation()
geocoder.nokia()
- now called asgeocoder.here()
geocoder.location()
- replaced withgeocoder.Location
, direct class sharinggeocoder.places()
geocoder.reverse()
geocoder.timezone()
Provider’s files relocated
All provider’s definition files relocated from project main folder to providers
module and related subdirectory inside. Directories structure respect provider
implementation function.
If you use direct provider classes imports, please update import statements. If you
use direct helper’s functions from geocoder
module - no changes expected.
geocoder.base.OneResult
changes
Property
self.raw
renamed toself.object_raw_json
to be more explainable in inside content. This change affects all subclasses (all providers).Property
self.housenumber
renamed toself.house_number
. Affect all nested provider’s files. Propertyself.house_number
removed and available only in concrete provider’s implementation.Most default properties values replaced from empty string
""
toNone
. Empty dicts in some cases left untouched. Please verify properties signatures.List of default properties become much smaller, some secondary properties, not required to internal
geocoder.base.OneResult
work was removed. This will allow new providers faster implementation. Such properties may exist in concrete implementations. Removed:accuracy
quality
house_number
street
city
state
country
postal
osm
locality
province
street_number
road
route
All parts of
geocoder.base.OneResult
now have huge docstrings and documentation, explaining all behaviour and approach.Some internal instance variables and properties renamed to be more concrete. This affect all children classes. List of renames:
json
toobject_json
geocoder.base.MultipleResultsQuery
changes
Class will enforce correct setting of
cls._URL
,cls._RESULT_CLASS
,cls._METHOD
,cls._PROVIDER
in nested classes on project initialization stage.Non-mandatory class variables
cls.method
andcls.provider
renamed tocls._METHOD
,cls._PROVIDER
and become mandatory, related tests added.Internal class structure changed. Now
geocoder.base.MultipleResultsQuery.__init__()
does not make an external query, and only do object initialization. This allow to initialize any amount of objects in advance usage cases (in loops). Query made ingeocoder.base.MultipleResultsQuery.__call__()
method. This change does not change helpers behaviour. I.e.geocoder.get_results()
and related functions already respect this change internally.Some internal instance variables and properties renamed to be more concrete. This affect all children classes. List of renames:
response
toraw_response
_list
toresults_list
ok
tohas_data
New instance variables/properties added:
is_called
- Hold status of external request. I.e. was or not was made.raw_json
- Hold unmodified JSON from provider for whole answer.
Removed functions:
geocoder.base.MultipleResultsQuery.set_default_result()
geocoder.base.MultipleResultsQuery.__init__()
method now have all default keyword arguments in signature, removing silent usage ofkwargs.get("something")
, this practice will be extended to all child classes.All parts of
geocoder.base.MultipleResultsQuery
now have huge docstrings and documentation, explaining all behaviour and approach.
All print statements replaced with logging module
List of affected files, functions and classes:
base.py
distance.py
geocoder.distance.haversine()
- warnings
bing_batch.py
geocoder.providers.BingBatchResult.debug()
bing_batch_forward.py
geocoder.providers.BingBatchForwardResult.debug()
bing_batch_reverse.py
geocoder.providers.BingBatchReverse.debug()
Removed(some temporary) project features
OSM type CLI/Debug output removed as non-well documented
kwargs approach and naming changes
There was a confusion between ‘deprecated’
limit
and newmaxRows
provider’s setting. All such cases renamed to self-explainedmax_results
.Everywhere, where it was possible all
**kwargs
replaced with complete list of function settings, usually with expected input type and defaults, if defaults available.
geocoder.providers.google
classes renamed
geocoder.providers.ElevationQuery
togeocoder.providers.GoogleElevationQuery
geocoder.providers.PlacesQuery
togeocoder.providers.GooglevPlacesQuery
geocoder.providers.ElevationResult
togeocoder.providers.GoogleElevationResult
geocoder.providers.PlacesResult
togeocoder.providers.GooglevPlacesResult