code/docs: sep handle_query from surplus, add docs
This commit is contained in:
parent
22f3a9a18c
commit
82c8cdf5f0
74
README.md
74
README.md
|
|
@ -8,6 +8,7 @@ Plus Code to iOS-Shortcuts-like shareable text
|
|||
- [API Reference](#api-reference)
|
||||
- [surplus.surplus()](#surplussurplus)
|
||||
- [surplus.parse_query()](#surplusparse_query)
|
||||
- [surplus.handle_query()](#surplushandle_query)
|
||||
- [surplus.Localcode](#surpluslocalcode)
|
||||
- [surplus.Latlong](#surpluslatlong)
|
||||
- [Developing](#developing)
|
||||
|
|
@ -44,16 +45,19 @@ pip install git+https://github.com/markjoshwel/surplus
|
|||
### Command-line Interface
|
||||
|
||||
```text
|
||||
usage: surplus [-h] [-d] query
|
||||
usage: surplus [-h] [-d] query [query ...]
|
||||
|
||||
Plus Code to iOS-Shortcuts-like shareable text
|
||||
|
||||
positional arguments:
|
||||
query full-length Plus Code (6PH58QMF+FX), local codes (8QMF+FX Singapore), or latlong (1.3336875, 103.7749375)
|
||||
query full-length Plus Code (6PH58QMF+FX),
|
||||
local code (8QMF+FX Singapore), or
|
||||
latlong (1.3336875, 103.7749375)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
-d, --debug prints lat, long and reverser response dict to stderr
|
||||
-d, --debug prints lat, long and reverser response
|
||||
dict to stderr
|
||||
```
|
||||
|
||||
### API Reference
|
||||
|
|
@ -76,9 +80,12 @@ pluscode to shareable text conversion function
|
|||
- arguments
|
||||
|
||||
- `query: str | surplus.Localcode | surplus.Latlong`
|
||||
str - normal longcode (6PH58QMF+FX)
|
||||
surplus.Localcode - shortcode with locality (8QMF+FX Singapore)
|
||||
surplus.Latlong - latlong
|
||||
- str
|
||||
normal longcode (6PH58QMF+FX)
|
||||
- [`surplus.Localcode`](#surpluslocalcode)
|
||||
shortcode with locality (8QMF+FX Singapore)
|
||||
- [`surplus.Latlong`](#surpluslatlong)
|
||||
latlong
|
||||
|
||||
- `reverser: typing.Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverser`
|
||||
latlong to location function, accesses a dict from .raw attribute of return object
|
||||
|
|
@ -97,22 +104,22 @@ pluscode to shareable text conversion function
|
|||
- returns `tuple[bool, str]`
|
||||
|
||||
- `(True, <str>)`
|
||||
conversion was successful, str is resultant text
|
||||
conversion succeeded, second element is the resultant string
|
||||
- `(False, <str>)`
|
||||
conversion failed, str is error message
|
||||
conversion failed, second element is an error message string
|
||||
|
||||
---
|
||||
|
||||
#### `surplus.parse_query()`
|
||||
|
||||
function that parses a string Plus Code, local code or latlong into a str, surplus.Localcode or surplus.Latlong respectively
|
||||
function that parses a string Plus Code, local code or latlong into a str, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) respectively
|
||||
|
||||
- signature:
|
||||
|
||||
```python
|
||||
def parse_query(
|
||||
query: str, debug: bool = False
|
||||
) -> tuple[bool, str | Localcode | Latlong]:
|
||||
) -> tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]:
|
||||
```
|
||||
|
||||
- arguments:
|
||||
|
|
@ -120,12 +127,43 @@ function that parses a string Plus Code, local code or latlong into a str, surpl
|
|||
- `query: str`
|
||||
string Plus Code, local code or latlong
|
||||
|
||||
- returns `tuple[bool, str | Localcode | Latlong]`
|
||||
- returns `tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]`
|
||||
|
||||
- `(True, <str | Localcode | Latlong>)`
|
||||
conversion was successful, second element is result
|
||||
- `(True, <str | surplus.Localcode | surplus.Latlong>)`
|
||||
conversion succeeded, second element is resultant Plus code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong)
|
||||
- `(False, <str>)`
|
||||
conversion failed, str is error message
|
||||
conversion failed, second element is an error message string
|
||||
|
||||
---
|
||||
|
||||
#### `surplus.handle_query()`
|
||||
|
||||
function that gets returns a [surplus.Latlong](#surpluslatlong) from a Plus Code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) object.
|
||||
used after [`surplus.parse_query()`](#surplusparse_query).
|
||||
|
||||
- signature:
|
||||
|
||||
```python
|
||||
def handle_query(
|
||||
query: str | Localcode | Latlong, debug: bool = False
|
||||
) -> tuple[Literal[True], Latlong] | tuple[Literal[False], str]:
|
||||
```
|
||||
|
||||
- arguments:
|
||||
|
||||
- `query: str | Localcode | Latlong`
|
||||
- str
|
||||
normal longcode (6PH58QMF+FX)
|
||||
- [`surplus.Localcode`](#surpluslocalcode)
|
||||
shortcode with locality (8QMF+FX Singapore)
|
||||
- [`surplus.Latlong`](#surpluslatlong)
|
||||
latlong
|
||||
|
||||
- returns `tuple[Literal[True], Latlong] | tuple[Literal[False], str]`
|
||||
- `(True, <surplus.Latlong>)`
|
||||
conversion succeeded, second element is a [`surplus.Latlong`](#surpluslatlong)
|
||||
- `(False, <str>)`
|
||||
conversion failed, second element is an error message string
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -136,9 +174,9 @@ function that parses a string Plus Code, local code or latlong into a str, surpl
|
|||
- parameters:
|
||||
|
||||
- `code: str`
|
||||
Plus Code - e.g.: "8QMF+FX"
|
||||
Plus Code - e.g.: `"8QMF+FX"`
|
||||
- `locality: str`
|
||||
e.g.: "Singapore"
|
||||
e.g.: `"Singapore"`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -162,9 +200,9 @@ method that calculates full-length Plus Code using locality
|
|||
- returns:
|
||||
|
||||
- `(True, <str>)`
|
||||
conversion was successful, str is resultant Plus Code
|
||||
conversion succeeded, second element is the resultant Plus Code string
|
||||
- `(False, <str>)`
|
||||
conversion failed, str is error message
|
||||
conversion failed, second element is an error message string
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
114
surplus.py
114
surplus.py
|
|
@ -32,7 +32,7 @@ For more information, please refer to <http://unlicense.org/>
|
|||
from argparse import ArgumentParser
|
||||
from collections import OrderedDict
|
||||
from sys import stderr
|
||||
from typing import Any, Callable, Final, NamedTuple
|
||||
from typing import Any, Callable, Final, Literal, NamedTuple
|
||||
|
||||
from geopy import Location # type: ignore
|
||||
from geopy.geocoders import Nominatim # type: ignore
|
||||
|
|
@ -131,49 +131,17 @@ def surplus(
|
|||
(True, <str>) - conversion was successful, str is resultant text
|
||||
(False, <str>) - conversion failed, str is error message
|
||||
"""
|
||||
lat: float = 0.0
|
||||
lon: float = 0.0
|
||||
_latlong = handle_query(query=query, debug=debug)
|
||||
|
||||
if isinstance(query, Latlong):
|
||||
lat, lon = query.lat, query.long
|
||||
if _latlong[0] is False:
|
||||
assert isinstance(_latlong[1], str)
|
||||
return False, _latlong[1]
|
||||
|
||||
else: # instances: str | Localcode
|
||||
str_pcode: str = ""
|
||||
|
||||
if isinstance(query, Localcode):
|
||||
result = query.full_length()
|
||||
|
||||
if not result[0]:
|
||||
return False, result[1]
|
||||
|
||||
str_pcode = result[1]
|
||||
|
||||
else:
|
||||
str_pcode = query
|
||||
assert isinstance(_latlong[1], Latlong)
|
||||
latlong = _latlong[1]
|
||||
|
||||
try:
|
||||
pcode = PlusCode(str_pcode)
|
||||
|
||||
except KeyError:
|
||||
return (
|
||||
False,
|
||||
"enter full-length Plus Code including area code, e.g.: 6PH58QMF+FX",
|
||||
)
|
||||
|
||||
except Exception as pcderr:
|
||||
return (
|
||||
False,
|
||||
f"error while decoding Plus Code: {pcderr.__class__.__name__} - {pcderr}",
|
||||
)
|
||||
|
||||
lat = pcode.area.center().lat
|
||||
lon = pcode.area.center().lon
|
||||
|
||||
if debug:
|
||||
stderr.write(f"debug: {lat=}, {lon=}\n")
|
||||
|
||||
try:
|
||||
_reversed: Location | None = reverser(f"{lat}, {lon}")
|
||||
_reversed: Location | None = reverser(f"{latlong.lat}, {latlong.long}")
|
||||
|
||||
if _reversed is None:
|
||||
raise Exception(f"reverser function returned None")
|
||||
|
|
@ -183,7 +151,7 @@ def surplus(
|
|||
except Exception as reverr:
|
||||
return (
|
||||
False,
|
||||
f"error while reversing latlong ({lat},{lon}): {reverr.__class__.__name__} - {reverr}",
|
||||
f"error while reversing latlong ({Latlong}): {reverr.__class__.__name__} - {reverr}",
|
||||
)
|
||||
|
||||
if debug:
|
||||
|
|
@ -251,7 +219,7 @@ def surplus(
|
|||
|
||||
def parse_query(
|
||||
query: str, debug: bool = False
|
||||
) -> tuple[bool, str | Localcode | Latlong]:
|
||||
) -> tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]:
|
||||
"""
|
||||
function that parses a string Plus Code, local code or latlong into a str,
|
||||
surplus.Localcode or surplus.Latlong respectively
|
||||
|
|
@ -268,7 +236,7 @@ def parse_query(
|
|||
|
||||
def _word_match(
|
||||
oquery: str, squery: list[str]
|
||||
) -> tuple[bool, str | Localcode | Latlong]:
|
||||
) -> tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]:
|
||||
"""
|
||||
internal helper code reuse function
|
||||
|
||||
|
|
@ -332,6 +300,66 @@ def parse_query(
|
|||
return _word_match(oquery=query, squery=squery)
|
||||
|
||||
|
||||
def handle_query(
|
||||
query: str | Localcode | Latlong, debug: bool = False
|
||||
) -> tuple[Literal[True], Latlong] | tuple[Literal[False], str]:
|
||||
"""
|
||||
function that gets returns a surplus.Latlong from a Plus Code string,
|
||||
surplus.Localcode or surplus.Latlong object.
|
||||
used after surplus.parse_query().
|
||||
|
||||
query: str | Localcode | Latlong
|
||||
|
||||
debug: bool = False
|
||||
|
||||
returns tuple[bool, str | Latlong]
|
||||
(True, Latlong) - conversion was successful, second element is latlong
|
||||
(False, <str>) - conversion failed, str is error message
|
||||
"""
|
||||
lat: float = 0.0
|
||||
lon: float = 0.0
|
||||
|
||||
if isinstance(query, Latlong):
|
||||
return True, query
|
||||
|
||||
else: # instances: str | Localcode
|
||||
str_pcode: str = ""
|
||||
|
||||
if isinstance(query, Localcode):
|
||||
result = query.full_length()
|
||||
|
||||
if not result[0]:
|
||||
return False, result[1]
|
||||
|
||||
str_pcode = result[1]
|
||||
|
||||
else:
|
||||
str_pcode = query
|
||||
|
||||
try:
|
||||
pcode = PlusCode(str_pcode)
|
||||
|
||||
except KeyError:
|
||||
return (
|
||||
False,
|
||||
"code given is not a full-length Plus Code (including area code), e.g.: 6PH58QMF+FX",
|
||||
)
|
||||
|
||||
except Exception as pcderr:
|
||||
return (
|
||||
False,
|
||||
f"error while decoding Plus Code: {pcderr.__class__.__name__} - {pcderr}",
|
||||
)
|
||||
|
||||
lat = pcode.area.center().lat
|
||||
lon = pcode.area.center().lon
|
||||
|
||||
if debug:
|
||||
stderr.write(f"debug: {lat=}, {lon=}\n")
|
||||
|
||||
return True, Latlong(lat=lat, long=lon)
|
||||
|
||||
|
||||
def cli() -> None:
|
||||
parser = ArgumentParser(
|
||||
prog="surplus",
|
||||
|
|
|
|||
Loading…
Reference in a new issue