2023-06-02 19:39:25 +00:00
# surplus
2023-06-03 08:31:02 +00:00
Plus Code to iOS-Shortcuts-like shareable text
- [Installing ](#installing )
- [Usage ](#usage )
- [Command-line Interface ](#command-line-interface )
- [API Reference ](#api-reference )
- [surplus.surplus() ](#surplussurplus )
- [surplus.parse_query() ](#surplusparse_query )
2023-06-16 07:05:05 +00:00
- [surplus.handle_query() ](#surplushandle_query )
2023-06-03 08:31:02 +00:00
- [surplus.Localcode ](#surpluslocalcode )
- [surplus.Latlong ](#surpluslatlong )
- [Developing ](#developing )
- [The format is wrong/different! ](#the-format-is-wrongdifferent )
- [Licence ](#licence )
2023-06-02 19:39:25 +00:00
```text
2023-06-03 10:26:40 +00:00
$ surplus 9R3J+R9 Singapore
2023-06-17 03:20:19 +00:00
surplus version 1.1.2
2023-06-02 19:39:25 +00:00
Thomson Plaza
2023-06-17 03:20:19 +00:00
301 Upper Thomson Road
2023-06-16 07:53:41 +00:00
Sin Ming, Bishan
2023-06-02 19:39:25 +00:00
574408
2023-06-16 07:53:41 +00:00
Central, Singapore
2023-06-02 19:39:25 +00:00
```
```python
2023-06-03 08:31:02 +00:00
>>> from surplus import surplus, Localcode
>>> Localcode(code="8RPQ+JW", locality="Singapore").full_length()
(True, '6PH58RPQ+JW')
>>> surplus("6PH58RPQ+JW")
2023-06-16 07:53:41 +00:00
(True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nCentral, Singapore')
2023-06-02 19:39:25 +00:00
```
## Installing
Install surplus directly from GitHub using pip:
```text
pip install git+https://github.com/markjoshwel/surplus
```
## Usage
2023-06-03 08:31:02 +00:00
### Command-line Interface
2023-06-02 19:39:25 +00:00
```text
2023-06-16 07:05:05 +00:00
usage: surplus [-h] [-d] query [query ...]
2023-06-02 19:39:25 +00:00
2023-06-03 08:31:02 +00:00
Plus Code to iOS-Shortcuts-like shareable text
2023-06-02 19:39:25 +00:00
positional arguments:
2023-06-16 07:05:05 +00:00
query full-length Plus Code (6PH58QMF+FX),
local code (8QMF+FX Singapore), or
latlong (1.3336875, 103.7749375)
2023-06-02 19:39:25 +00:00
options:
-h, --help show this help message and exit
2023-06-16 07:05:05 +00:00
-d, --debug prints lat, long and reverser response
dict to stderr
2023-06-02 19:39:25 +00:00
```
2023-06-03 08:31:02 +00:00
### API Reference
#### `surplus.surplus()`
pluscode to shareable text conversion function
- signature
```python
def surplus(
query: str | Localcode | Latlong,
2023-06-03 10:26:40 +00:00
reverser: typing.Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverse,
2023-06-03 08:31:02 +00:00
debug: bool = False,
) -> tuple[bool, str]:
...
```
- arguments
- `query: str | surplus.Localcode | surplus.Latlong`
2023-06-16 07:05:05 +00:00
- str
normal longcode (6PH58QMF+FX)
- [`surplus.Localcode` ](#surpluslocalcode )
shortcode with locality (8QMF+FX Singapore)
- [`surplus.Latlong` ](#surpluslatlong )
latlong
2023-06-03 08:31:02 +00:00
2023-06-03 10:26:40 +00:00
- `reverser: typing.Callable = geopy.geocoders.Nominatim(user_agent="surplus").reverser`
latlong to location function, accesses a dict from .raw attribute of return object
function should be able to take a string with two floats and return a `geopy.Location` -like object (None checking is done)
2023-06-03 08:31:02 +00:00
```python
# code used by surplus
location: dict[str, Any] = reverser(f"{lat}, {lon}").raw
```
2023-06-03 10:26:40 +00:00
dict should be similar to [nominatim raw dicts ](https://nominatim.org/release-docs/latest/api/Output/#addressdetails )
2023-06-03 08:31:02 +00:00
- `debug: bool = False`
prints lat, long and reverser response dict to stderr
- returns `tuple[bool, str]`
- `(True, <str>)`
2023-06-16 07:05:05 +00:00
conversion succeeded, second element is the resultant string
2023-06-03 08:31:02 +00:00
- `(False, <str>)`
2023-06-16 07:05:05 +00:00
conversion failed, second element is an error message string
2023-06-03 08:31:02 +00:00
---
#### `surplus.parse_query()`
2023-06-16 07:05:05 +00:00
function that parses a string Plus Code, local code or latlong into a str, [`surplus.Localcode` ](#surpluslocalcode ) or [`surplus.Latlong` ](#surpluslatlong ) respectively
2023-06-03 08:31:02 +00:00
- signature:
```python
2023-06-03 10:26:40 +00:00
def parse_query(
query: str, debug: bool = False
2023-06-16 07:05:05 +00:00
) -> tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]:
2023-06-03 08:31:02 +00:00
```
2023-06-03 10:26:40 +00:00
2023-06-03 08:31:02 +00:00
- arguments:
- `query: str`
string Plus Code, local code or latlong
2023-06-16 07:05:05 +00:00
- returns `tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]`
2023-06-03 08:31:02 +00:00
2023-06-16 07:05:05 +00:00
- `(True, <str | surplus.Localcode | surplus.Latlong>)`
conversion succeeded, second element is resultant Plus code string, [`surplus.Localcode` ](#surpluslocalcode ) or [`surplus.Latlong` ](#surpluslatlong )
2023-06-03 08:31:02 +00:00
- `(False, <str>)`
2023-06-16 07:05:05 +00:00
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
2023-06-03 08:31:02 +00:00
---
#### `surplus.Localcode`
`typing.NamedTuple` representing short Plus Code with locality
- parameters:
- `code: str`
2023-06-16 07:05:05 +00:00
Plus Code - e.g.: `"8QMF+FX"`
2023-06-03 08:31:02 +00:00
- `locality: str`
2023-06-16 07:05:05 +00:00
e.g.: `"Singapore"`
2023-06-03 08:31:02 +00:00
---
##### `surplus.Localcode.full_length()`
method that calculates full-length Plus Code using locality
- signature:
```python
2023-06-03 10:26:40 +00:00
def full_length(
self, geocoder: Callable = Nominatim(user_agent="surplus").geocode
) -> tuple[bool, str]:
2023-06-03 08:31:02 +00:00
```
2023-06-03 10:26:40 +00:00
- arguments:
- `geocoder: typing.Callable = geopy.geocoders.Nominatim(user_agent="surplus").geocode`
place/locality to location function, accesses .longitude and .latitude if returned object is not None
2023-06-03 08:31:02 +00:00
- returns:
- `(True, <str>)`
2023-06-16 07:05:05 +00:00
conversion succeeded, second element is the resultant Plus Code string
2023-06-03 08:31:02 +00:00
- `(False, <str>)`
2023-06-16 07:05:05 +00:00
conversion failed, second element is an error message string
2023-06-03 08:31:02 +00:00
---
#### `surplus.Latlong`
`typing.NamedTuple` representing a pair of latitude and longitude coordinates
- parameters:
- `lat: float`
latitudinal coordinate
- `long: float`
longitudinal coordinate
2023-06-02 19:39:25 +00:00
## Developing
Prerequisites:
- [Python >=3.10 ](https://www.python.org/ )
- [Poetry ](https://python-poetry.org/ )
Alternatively, use [devbox ](https://get.jetpack.io/devbox ) for a hermetic development environment powered by [Nix ](https://nixos.org/ ).
```text
devbox shell # skip this if you aren't using devbox
poetry install
poetry shell
```
2023-06-03 08:31:02 +00:00
## The format is wrong/different!
If surplus generates wrong text for a particular Plus Code,
[submit an issue ](https://github.com/markjoshwel/surplus/issues/new ).
Ensure you detail the following:
1. The erroneous Plus Code, local code or latlong, or a similar coordinate that reproduces the same error
2. Output from the terminal, with `--debug` enabled or `debug=True`
3. How it should look like instead
2023-06-02 19:39:25 +00:00
## Licence
surplus is free and unencumbered software released into the public domain.
For more information, please refer to the [UNLICENCE ](UNLICENCE ), < http: // unlicense . org /> or the Python module docstring.