Skip to content

Commit 91f08cc

Browse files
erikboserikbos
committed
- Fixed error handling of decode() method in case of decode failure.
- Added Python method documentation to readme.
1 parent 9bf4ee4 commit 91f08cc

File tree

2 files changed

+105
-34
lines changed

2 files changed

+105
-34
lines changed

‎README.md‎

Lines changed: 102 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Mapcode package for Python
1+
# Mapcode module for Python
22

33
Copyright (C) 2014-2015 Stichting Mapcode Foundation (http://www.mapcode.com)
44

55
----
66

7-
This Python project contains a package to encode latitude/longitude pairs to mapcodes
7+
This Python project contains a module to encode latitude/longitude pairs to mapcodes
88
and to decode mapcodes back to latitude/longitude pairs.
99

1010
If you wish to use mapcodes in your own application landscape, consider using running an instance of the
@@ -34,67 +34,141 @@ At the moment this module is still in development!
3434

3535
# Bug Reports and New Feature Requests
3636

37-
If you encounter any problems with this package, don't hesitate to use the `Issues` session to file your issues.
37+
If you encounter any problems with this module, don't hesitate to use the `Issues` session to file your issues.
3838
Normally, one of our developers should be able to comment on them and fix.
3939

4040
# Prequisites
4141

42-
As the Python modules relies upon the Mapcode C library you will
42+
As this Python module relies upon the Mapcode C library you will
4343
need to have a compiler installed to be able to build and install
4444
this module.
4545

4646
The assumption is that the mapcode-cpp source is available in
4747
../mapcode-cpp/mapcodelib, if it located in a different place you
48-
will have to update the include directory in setup.py
48+
will have to update the include directory in setup.py.
4949

5050

5151
# Installation
5252

53-
Get both the Python and C repositories using:
53+
Get both the mapcode Python and C repositories using:
5454

5555
```
5656
git clone https://github.com/mapcode-foundation/mapcode-python
5757
git clone https://github.com/mapcode-foundation/mapcode-cpp
5858
cd mapcode-python
5959
```
6060

61-
Compile the package in current directory using:
61+
Compile the package in current directory: `python setup.py --inplace`
62+
Install in your Python environment using: `python setup.py install`
6263

64+
65+
## Usage in Python
66+
67+
```python
68+
import mapcode
6369
```
64-
python setup.py --inplace
70+
dir (mapcode)
71+
72+
e.g.:
73+
74+
import mapcode
75+
dir(mapcode)
76+
['__doc__', '__file__', '__name__', '__package__', 'decode', 'encode', 'encode_single', 'isvalid', 'version']
6577
```
6678
67-
Install in your Python environment using:
79+
## Mapcode syntax validation
80+
81+
To validate the syntax of a mapcode string use the isvalid() method.
6882
83+
```python
84+
print mapcode.isvalid('VHXG9.FQ9Z')
85+
True
86+
print mapcode.isvalid('Amsterdam')
87+
False
6988
```
70-
python setup.py install
89+
90+
As optional parameter you can pass 1 or 0: if you pass 1, full mapcodes
91+
(including optional territory context) will be recognized. If you pass 0,
92+
only “proper” mapcodes will be recognized.
93+
94+
```python
95+
print mapcode.isvalid('NLD 49.4V', 1)
96+
True
97+
print mapcode.isvalid('VHXG9.FQ9Z',0)
98+
True
99+
print mapcode.isvalid('NLD 49.4V', 0)
100+
False
101+
102+
(This one fails as it is not a full mapcode)
71103
```
72104

73105

74-
# Usage
106+
## Enconding latitude, longitude to a mapcode
107+
108+
For encoding there are two methods avaiable.
109+
110+
Use the encode_single() method to find one possible mapcode. Optionally
111+
a territory code can be provide to encode for just that territory.
75112

76113

77114
```python
78-
import mapcode
115+
print mapcode.encode_single(52.376514, 4.908542)
116+
NLD 49.4V
79117

80-
dir (mapcode)
118+
For this coordinate there are multiple mapcodes possible, hence providing
119+
a territory code can give a different one.
81120

82-
print mapcode.__doc__
83-
print mapcode.version()
84-
print mapcode.decode('NLD 49.4V','')
85-
print mapcode.decode('IN VY.HV','USA')
86-
print mapcode.decode('IN VY.HV','RUS')
87-
print mapcode.decode('D6.58','RU-IN DK.CN0')
88-
print mapcode.decode('IN VY.HV','')
89-
print mapcode.decode('RU-IN VY.HV','')
90-
print mapcode.decode('IN VY.HV','RUS')
121+
print mapcode.encode_single(41.851944, 12.433114)
122+
ITA 0Z.0Z
123+
print mapcode.encode_single(41.851944, 12.433114, 'AAA')
124+
TJKM1.D2Z6
125+
```
91126

92-
print mapcode.isvalid('NLD 49.4V', 1)
93-
print mapcode.isvalid('VHXG9.FQ9Z',0)
127+
Use the encode() method to find all possible mapcodes. Optionally
128+
a territory code can be provide to encode for just that territory.
129+
130+
131+
```python
132+
print mapcode.encode(52.376514, 4.908542)
133+
[['49.4V', 'NLD'], ['G9.VWG', 'NLD'], ['DL6.H9L', 'NLD'], ['P25Z.N3Z', 'NLD'], ['VHXGB.1J9J', 'AAA']]
134+
```
135+
136+
A territory code can be provide to encode for just that territory.
137+
138+
```python
139+
print mapcode.encode(52.376514, 4.908542, 'NLD')
140+
print mapcode.encode(39.609999,45.949999, 'AZE')
141+
[['XLT.HWB', 'AZE'], ['2Z.05XL', 'AZE'], ['6N49.HHV', 'AZE']]```
142+
143+
## Decoding mapcode to latitude, longitude
94144

95-
print mapcode.encode_single(52.376514, 4.908542, 'NLD', 2)
96-
print mapcode.encode_single(41.938434,12.433114, None, 2)
145+
Use the decode() method to decode a mapcode back to latitude and longitude.
97146

98-
print mapcode.encode(52.376514, 4.908542, 'NLD', 2)
99-
print mapcode.encode(39.609999,45.949999, 'AZE', 0)
147+
```python
148+
print mapcode.decode('NLD 49.4V')
149+
(52.376514, 4.908542)
150+
print mapcode.decode('IN VY.HV')
151+
(43.193485, 44.826592)
152+
print mapcode.decode('VHXG9.DNRF')
153+
(52.371422, 4.872497)
100154
```
155+
156+
An optional territory code can be provide to disambiguate the mapcode.
157+
158+
A territory is require to decode this mapcode:
159+
160+
```python
161+
print mapcode.decode('D6.58')
162+
False
163+
print mapcode.decode('D6.58','RU-IN DK.CN0')
164+
(43.259275, 44.77198)
165+
```
166+
167+
A territory is require to give context:
168+
169+
```python
170+
print mapcode.decode('IN VY.HV','USA')
171+
(39.72795, -86.118444)
172+
print mapcode.decode('IN VY.HV','RUS')
173+
(43.193485, 44.826592)```
174+
```

‎mapcodemodule.c‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,8 @@ static PyObject *decode(PyObject *self, PyObject *args)
7373
} else
7474
territorycode = 0;
7575

76-
decodeMapcodeToLatLon(&latitude, &longitude, mapcode, territorycode);
76+
if (decodeMapcodeToLatLon(&latitude, &longitude, mapcode, territorycode))
77+
return Py_False;
7778

7879
return Py_BuildValue("dd", latitude, longitude);
7980
}
@@ -101,8 +102,6 @@ static PyObject *encode(PyObject *self, PyObject *args)
101102

102103
if (territoryname) {
103104
territorycode = convertTerritoryIsoNameToCode(territoryname, 0);
104-
printf("debug1: encode: territorystring: %s, code: %d\n", territoryname, territorycode);
105-
106105
if (territorycode < 0) {
107106
return Py_False;
108107
}
@@ -160,8 +159,7 @@ static PyObject *encode_single(PyObject *self, PyObject *args)
160159
}
161160

162161

163-
/* The methods we have. */
164-
162+
/* The methods we expose in Python. */
165163
static PyMethodDef mapcode_methods[] = {
166164
{ "version", version, METH_VARARGS, version_doc },
167165
{ "isvalid", isvalid, METH_VARARGS, isvalid_doc },
@@ -173,7 +171,6 @@ static PyMethodDef mapcode_methods[] = {
173171

174172

175173
/* Initialisation that gets called when module is imported. */
176-
177174
PyMODINIT_FUNC initmapcode(void)
178175
{
179176
Py_InitModule("mapcode", mapcode_methods);

0 commit comments

Comments
 (0)