mark/surplus
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

s+,docs: future is now

Browse source 
pyproj: remove py.typed include, poetry does this automatically
ci(qc): fix typo
ci(release): duplicate non-versioned wheels
This commit is contained in:
Mark Joshwel 2023-09-03 14:23:40 +00:00
parent 35f19b8bc9
commit 9752710f82
5 changed files with 155 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/checks.yml vendored
View file

@ -19,7 +19,7 @@ jobs:
- name: install dependencies - name: install dependencies
run: devbox run poetry install run: devbox run poetry install
- name: buil wheel - name: build wheel
id: build id: build
run: devbox run poetry build run: devbox run poetry build

3
.github/workflows/publish-slsa3.yml vendored
View file

@ -27,6 +27,9 @@ jobs:
id: build id: build
run: devbox run poetry build run: devbox run poetry build
- name: duplicate non-versioned wheel
run: cp dist/surplus-*.whl dist/surplus-py3-none-any.whl
- name: generate provenance subjects - name: generate provenance subjects
id: hash id: hash
run: | run: |

253
README.md
View file

@ -1,25 +1,12 @@
# surplus # surplus
> **Warning**
>
> **this is surplus `2.0.0`.**
> surplus is being rewritten to better incorporate with
> [sandplus](https://github.com/markjoshwel/sandplus.git).
> sandplus is surplus's Android application accompaniment, written in Kotlin with Jetpack
> Compose.
>
> you are on the `future` branch. if you see this warning, that means code is not
> finalised and ready to be used.
> want the old, stable, working codebase? see the
> [`main`](https://github.com/markjoshwel/surplus/tree/main) branch.
surplus is a Python script to convert surplus is a Python script to convert
[Google Maps Plus Codes](https://maps.google.com/pluscodes/) [Google Maps Plus Codes](https://maps.google.com/pluscodes/)
to iOS Shortcuts-like shareable text. to iOS Shortcuts-like shareable text.
- [installation](#installation) - [installation](#installation)
- [usage](#usage) - [usage](#usage)
- [command-line usage](#command-line-usaage) - [command-line usage](#command-line-usage)
- [example api usage](#example-api-usage) - [example api usage](#example-api-usage)
- [developer's guide](#developers-guide) - [developer's guide](#developers-guide)
- [contributor's guide](#contributors-guide) - [contributor's guide](#contributors-guide)
@ -42,16 +29,27 @@ Central, Singapore
## installation ## installation
> **Note** > [!IMPORTANT]
> python 3.11 or later is required due to a bug in earlier versions. > python 3.11 or later is required due to a bug in earlier versions.
> [(python/cpython#88089)](https://github.com/python/cpython/issues/88089) > [(python/cpython#88089)](https://github.com/python/cpython/issues/88089)
install surplus directly from the repository using pip: for most, you can install surplus built from the latest stable release:
```text ```text
pip install git+https://github.com/markjoshwel/surplus.git@future pip install https://github.com/markjoshwel/surplus/releases/latest/download/surplus-py3-none-any.whl
``` ```
or directly from the repository using pip:
```text
pip install git+https://github.com/markjoshwel/surplus.git@main
```
surplus is also a public domain dedicated [single python file](surplus/surplus.py), so
feel free to grab that and embed it into your own program as you see fit.
see [licence](#licence) for licensing information.
## usage ## usage
### command-line usage ### command-line usage
@ -94,14 +92,14 @@ here are a few examples to get you quickly started using surplus in your own pro
2. handle queries seperately 2. handle queries seperately
```python ```python
>>> import surplus >>> import surplus
>>> behaviour = surplus.Behaviour("6PH58R3M+F8") >>> behaviour = surplus.Behaviour("6PH58R3M+F8")
>>> query = surplus.parse_query(behaviour) >>> query = surplus.parse_query(behaviour)
>>> result = surplus.surplus(query.get(), behaviour) >>> result = surplus.surplus(query.get(), behaviour)
>>> result.get() >>> result.get()
'MacRitchie Nature Trail\nCentral Water Catchment\n574325\nCentral, Singapore' 'MacRitchie Nature Trail\nCentral Water Catchment\n574325\nCentral, Singapore'
``` ```
3. start from a Query object 3. start from a Query object
@ -117,10 +115,12 @@ here are a few examples to get you quickly started using surplus in your own pro
notes: notes:
- you can change what surplus does by passing in a custom `Behaviour` object. - you can change what surplus does by passing in a custom [`Behaviour`](#class-behaviour)
object
- most surplus functions return a `Result` object. while you can `.get()` the Result to - most surplus functions return a [`Result`](#class-result) object. while you can
obtain the proper return value, this is dangerous and might raise an exception. call [`.get()`](#resultget) to obtain the proper return value, this is dangerous and
might raise an exception
see the [api reference](#api-reference) for more information. see the [api reference](#api-reference) for more information.
@ -152,7 +152,7 @@ for information on surplus's exposed api, see the [api reference](#api-reference
when contributing your first changes, please include an empty commit for a copyright when contributing your first changes, please include an empty commit for a copyright
waiver using the following message (replace 'Your Name' with your name or nickname): waiver using the following message (replace 'Your Name' with your name or nickname):
``` ```text
Your Name Copyright Waiver Your Name Copyright Waiver
I dedicate any and all copyright interest in this software to the I dedicate any and all copyright interest in this software to the
@ -166,7 +166,7 @@ the command to create an empty commit is `git commit --allow-empty`
### reporting incorrect output ### reporting incorrect output
> **Note** > [!NOTE]
> this section is independent from the rest of the contributing section. > this section is independent from the rest of the contributing section.
different output from the iOS Shortcuts app is expected, however incorrect output is not. different output from the iOS Shortcuts app is expected, however incorrect output is not.
@ -191,7 +191,7 @@ and do the following:
[`--debug` flag](#command-line-usage) passed to the surplus CLI or with [`--debug` flag](#command-line-usage) passed to the surplus CLI or with
`debug=True` set in function calls. `debug=True` set in function calls.
> **Note** > [!NOTE]
> if you are using the surplus API and have passed custom stdout and stderr parameters > if you are using the surplus API and have passed custom stdout and stderr parameters
> to redirect output, include that instead. > to redirect output, include that instead.
@ -210,7 +210,7 @@ and do the following:
- iOS Shortcuts Output - iOS Shortcuts Output
``` ```text
Plaza Singapura Plaza Singapura
68 Orchard Rd 68 Orchard Rd
238839 238839
@ -219,7 +219,7 @@ and do the following:
- surplus Output - surplus Output
``` ```text
Plaza Singapura Plaza Singapura
68 Orchard Road 68 Orchard Road
Museum Museum
@ -230,16 +230,12 @@ and do the following:
this _should not_ be reported as incorrect, as the only difference between the two is this _should not_ be reported as incorrect, as the only difference between the two is
that surplus displays more information. that surplus displays more information.
note: for singaporean readers, "Musuem" here is correct as it refers to the
[Museum planning area](https://en.wikipedia.org/wiki/Museum_Planning_Area),
in which Plaza Singapura is located in.
other examples that _should not_ be reported are: other examples that _should not_ be reported are:
- name of place is incorrect/different - name of place is incorrect/different
this may be due to incorrect data from the geolocator function, which is OpenStreetMap Nominatim by default. this may be due to incorrect data from the geolocator function, which is OpenStreetMap Nominatim by default.
in the case of Nominatim, it means that there the data on OpenStreetMap is incorrect. in the case of Nominatim, it means that the data on OpenStreetMap is incorrect.
(_if so, then consider updating OpenStreetMap to help not just you, but other surplus (_if so, then consider updating OpenStreetMap to help not just you, but other surplus
and OpenStreetMap users!_) and OpenStreetMap users!_)
@ -253,19 +249,19 @@ of incorrect outputs.
## the technical details of surplus's output ## the technical details of surplus's output
> **Note** > [!NOTE]
> this is a breakdown of surplus's output when converting to shareable text. > this is a breakdown of surplus's output when converting to shareable text.
> when converting to other output types, n > when converting to other output types, output may be different.
``` ```text
$ s+ --debug 8QJF+RP Singapore $ s+ --debug 8QJF+RP Singapore
surplus version 2.0.0, debug mode surplus version 2.0.0, debug mode
debug: behaviour.query=['8QJF+RP', 'Singapore'] debug: parse_query: behaviour.query=['8QJF+RP', 'Singapore']
debug: portion_plus_code='8QJF+RP', portion_locality='Singapore' debug: _match_plus_code: portion_plus_code='8QJF+RP', portion_locality='Singapore'
debug: query=Result(value=LocalCodeQuery(code='8QJF+RP', locality='Singapore'), error=None) debug: cli: query=Result(value=LocalCodeQuery(code='8QJF+RP', locality='Singapore'), error=None)
debug: latlong.get()=Latlong(latitude=1.3320625, longitude=103.7743125) debug: cli: latlong.get()=Latlong(latitude=1.3320625, longitude=103.7743125)
debug: location={'amenity': 'Ngee Ann Polytechnic', 'house_number': '535', 'road': 'Clementi Road', 'suburb': 'Bukit Timah', 'city': 'Singapore', 'county': 'Northwest', 'ISO3166-2-lvl6': 'SG-03', 'postcode': '599489', 'country': 'Singapore', 'country_code': 'sg', 'raw': "{...}", 'latitude': '1.33318835', 'longitude': '103.77461234638255'} debug: cli: location={'amenity': 'Ngee Ann Polytechnic', 'house_number': '535', 'road': 'Clementi Road', 'suburb': 'Bukit Timah', 'city': 'Singapore', 'county': 'Northwest', 'ISO3166-2-lvl6': 'SG-03', 'postcode': '599489', 'country': 'Singapore', 'country_code': 'sg', 'raw': "{...}", 'latitude': '1.33318835', 'longitude': '103.77461234638255'}
debug: seen_names=['Ngee Ann Polytechnic', 'Clementi Road'] debug: _generate_text: seen_names=['Ngee Ann Polytechnic', 'Clementi Road']
debug: _generate_text_line: [True] -> True -------- 'Ngee Ann Polytechnic' debug: _generate_text_line: [True] -> True -------- 'Ngee Ann Polytechnic'
debug: _generate_text_line: [True] -> True -------- '535' debug: _generate_text_line: [True] -> True -------- '535'
debug: _generate_text_line: [True] -> True -------- 'Clementi Road' debug: _generate_text_line: [True] -> True -------- 'Clementi Road'
@ -292,8 +288,8 @@ variables
- **variable `behaviour.query`** - **variable `behaviour.query`**
query split by comma, comes from the original query string or a list of strings from space-splitting the original query
[`argparse.ArgumentParser.parse_args`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args) string passed to [`parse_query()`](#def-parse_query) for parsing
```text ```text
$ s+ 77Q4+7X Austin, Texas, USA $ s+ 77Q4+7X Austin, Texas, USA
@ -302,6 +298,12 @@ variables
behaviour.query -> ['77Q4+7X', 'Austin', 'Texas', 'USA'] behaviour.query -> ['77Q4+7X', 'Austin', 'Texas', 'USA']
``` ```
```text
>>> surplus("77Q4+7X Austin, Texas, USA", surplus.Behaviour())
behaviour.query -> '77Q4+7X Austin, Texas, USA'
```
- **variables `portion_plus_code` and `portion_locality`** - **variables `portion_plus_code` and `portion_locality`**
@ -310,36 +312,33 @@ variables
represents the plus code and locality portions of a represents the plus code and locality portions of a
[shortened plus code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening) [shortened plus code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening)
(_referred to as a "local code" in the codebase_) respectively. (_referred to as a "local code" in the codebase_) respectively
- **variable `query`** - **variable `query`**
query is a variable of type `surplus.Result[surplus.Query]`, where `surplus.Query` is query is a variable of type [`Result`](#class-result)[`[Query]`](#query)
a TypeAlias of `PlusCodeQuery | LocalCodeQuery | LatlongQuery | StringQuery`.
this variable is displayed to show what query type this variable is displayed to show what query type [`parse_query()`](#def-parse_query) has
`surplus.parse_query` has recognised, and if there were any errors recognised, and if there were any errors during query parsing
during query parsing.
- **expression `latlong.get()=`** - **expression `latlong.get()=`**
(_only shown if the query is a plus code_) (_only shown if the query is a plus code_)
the latitude longitude coordinates derived from the plus code. the latitude longitude coordinates derived from the plus code
- **variable `location`** - **variable `location`**
the response dictionary from the reverser passed to the response dictionary from the reverser function passed to
[`surplus.surplus()`](#surplussurplus) [`surplus()`](#def-surplus)
for more information on what the dictionary should contain or how it should look like, for more information on the reverser function, see [`Behaviour`](#class-behaviour) and
see the [playground notebook](playground.ipynb), documentation on surplus.Behaviour or [`default_reverser`](#def-default_reverser)
the surplus's implementation of the reverser function in `surplus.default_reverser`.
- **variable `seen_names`** - **variable `seen_names`**
a list of unique important names found in certain nominatim keys used in final output a list of unique important names found in certain nominatim keys used in final output
lines 0-3. lines 0-3
- **`_generate_text_line` seen name checks** - **`_generate_text_line` seen name checks**
@ -351,15 +350,15 @@ variables
``` ```
a check is done on shareable text line 4 keys (`SHAREABLE_TEXT_LINE_4_KEYS` - general a check is done on shareable text line 4 keys (`SHAREABLE_TEXT_LINE_4_KEYS` - general
regional location) to reduce repeated elements found in `seen_names`. regional location) to reduce repeated elements found in `seen_names`
reasoning is, if an element on line 4 (general regional location) is the exact same as reasoning is, if an element on line 4 (general regional location) is the exact same as
a previously seen name, there is no need to include the element. a previously seen name, there is no need to include the element
- **filter function boolean list** - **filter function boolean list**
`_generate_text_line`, an internal function defined inside `_generate_text` can be `_generate_text_line`, an internal function defined inside `_generate_text` can be
passed a filter function as a way to filter out certain elements on a line. passed a filter function as a way to filter out certain elements on a line
```python ```python
# the filter used in _generate_text, for line 4's seen name checks # the filter used in _generate_text, for line 4's seen name checks
@ -383,9 +382,9 @@ variables
the current iteration from iterating through a list of strings containing elements the current iteration from iterating through a list of strings containing elements
from line 4. (general regional location) from line 4. (general regional location)
breakdown of each output line, accompanied by their nominatim key: line breakdown of shareable text output, accompanied by their Nominatim keys:
``` ```text
0 name of a place 0 name of a place
1 building name 1 building name
2 highway name 2 highway name
@ -401,7 +400,7 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
The University of Queensland The University of Queensland
Ngee Ann Polytechnic Ngee Ann Polytechnic
Botanic Gardens Botanic Gardens
@ -409,7 +408,7 @@ breakdown of each output line, accompanied by their nominatim key:
- nominatim keys - nominatim keys
``` ```text
emergency, historic, military, natural, landuse, place, railway, man_made, emergency, historic, military, natural, landuse, place, railway, man_made,
aerialway, boundary, amenity, aeroway, club, craft, leisure, office, mountain_pass, aerialway, boundary, amenity, aeroway, club, craft, leisure, office, mountain_pass,
shop, tourism, bridge, tunnel, waterway shop, tourism, bridge, tunnel, waterway
@ -419,14 +418,14 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
Novena Square Office Tower A Novena Square Office Tower A
Visitor Centre Visitor Centre
``` ```
- nominatim keys - nominatim keys
``` ```text
building building
``` ```
@ -434,14 +433,14 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
Marina Coastal Expressway Marina Coastal Expressway
Lornie Highway Lornie Highway
``` ```
- nominatim keys - nominatim keys
``` ```text
highway highway
``` ```
@ -449,7 +448,7 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
535 Clementi Road 535 Clementi Road
Macquarie Street Macquarie Street
Braddell Road Braddell Road
@ -457,7 +456,7 @@ breakdown of each output line, accompanied by their nominatim key:
- nominatim keys - nominatim keys
``` ```text
house_number, house_name, road house_number, house_name, road
``` ```
@ -465,7 +464,7 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
St Lucia, Greater Brisbane St Lucia, Greater Brisbane
The Drag, Austin The Drag, Austin
Toa Payoh Crest Toa Payoh Crest
@ -473,7 +472,7 @@ breakdown of each output line, accompanied by their nominatim key:
- nominatim keys - nominatim keys
``` ```text
residential, neighbourhood, allotments, quarter, city_district, district, borough, residential, neighbourhood, allotments, quarter, city_district, district, borough,
suburb, subdivision, municipality, city, town, village suburb, subdivision, municipality, city, town, village
``` ```
@ -482,7 +481,7 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
310131 310131
78705 78705
4066 4066
@ -490,7 +489,7 @@ breakdown of each output line, accompanied by their nominatim key:
- nominatim key - nominatim key
``` ```text
postcode postcode
``` ```
@ -498,7 +497,7 @@ breakdown of each output line, accompanied by their nominatim key:
- examples - examples
``` ```text
Travis County, Texas, United States Travis County, Texas, United States
Southeast, Singapore Southeast, Singapore
Queensland, Australia Queensland, Australia
@ -506,7 +505,7 @@ breakdown of each output line, accompanied by their nominatim key:
- nominatim keys - nominatim keys
``` ```text
region, county, state, state_district, country, continent region, county, state, state_district, country, continent
``` ```
@ -515,6 +514,8 @@ breakdown of each output line, accompanied by their nominatim key:
- [constants](#constants) - [constants](#constants)
- [exception classes](#exception-classes) - [exception classes](#exception-classes)
- [types](#types) - [types](#types)
- [`Query`](#query)
- [`ResultType`](#resulttype)
- [`class Behaviour`](#class-behaviour) - [`class Behaviour`](#class-behaviour)
- [`class ConversionResultTypeEnum`](#class-conversionresulttypeenum) - [`class ConversionResultTypeEnum`](#class-conversionresulttypeenum)
- [`class Result`](#class-result) - [`class Result`](#class-result)
@ -522,10 +523,20 @@ breakdown of each output line, accompanied by their nominatim key:
- [`Result.cry()`](#resultcry) - [`Result.cry()`](#resultcry)
- [`Result.get()`](#resultget) - [`Result.get()`](#resultget)
- [`class Latlong`](#class-latlong) - [`class Latlong`](#class-latlong)
- [`Latlong.__str__()`](#latlong__str__)
- [`class PlusCodeQuery`](#class-pluscodequery) - [`class PlusCodeQuery`](#class-pluscodequery)
- [`PlusCodeQuery.to_lat_long_coord()`](#pluscodequeryto_lat_long_coord)
- [`PlusCodeQuery.__str__()`](#pluscodequery__str__)
- [`class LocalCodeQuery`](#class-localcodequery) - [`class LocalCodeQuery`](#class-localcodequery)
- [`LocalCodeQuery.to_full_plus_code()`](#localcodequeryto_full_plus_code)
- [`LocalCodeQuery.to_lat_long_coord()`](#localcodequeryto_lat_long_coord)
- [`LocalCodeQuery.__str__()`](#localcodequery__str__)
- [`class LatlongQuery`](#class-latlongquery) - [`class LatlongQuery`](#class-latlongquery)
- [`LatlongQuery.to_lat_long_coord()`](#latlongqueryto_lat_long_coord)
- [`LatlongQuery.__str__()`](#latlongquery__str__)
- [`class StringQuery`](#class-stringquery) - [`class StringQuery`](#class-stringquery)
- [`StringQuery.to_lat_long_coord()`](#stringqueryto_lat_long_coord)
- [`StringQuery.__str__()`](#stringquery__str__)
- [`def surplus()`](#def-surplus) - [`def surplus()`](#def-surplus)
- [`def parse_query()`](#def-parse_query) - [`def parse_query()`](#def-parse_query)
- [`def default_geocoder()`](#def-default_geocoder) - [`def default_geocoder()`](#def-default_geocoder)
@ -593,13 +604,13 @@ ResultType = TypeVar("ResultType")
### `class Behaviour` ### `class Behaviour`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing how surplus operations should behave representing how surplus operations should behave
attributes attributes
- `query: str | list[str] = ""` - `query: str | list[str] = ""`
original user-passed query string or a list of strings from splitting user-passed query original user-passed query string or a list of strings from splitting user-passed query
string by spaces string by spaces
- `geocoder: typing.Callable[[str], Latlong] = default_geocoder` - `geocoder: typing.Callable[[str], Latlong] = default_geocoder`
@ -607,8 +618,8 @@ attributes
[`Latlong`](#class-latlong), exceptions are handled by the caller [`Latlong`](#class-latlong), exceptions are handled by the caller
- `reverser: Callable[[Latlong], dict[str, Any]] = default_reverser` - `reverser: Callable[[Latlong], dict[str, Any]] = default_reverser`
[`Latlong`] object to dictionary function, must take in a string and return a dict. [`Latlong`](#class-latlong) object to dictionary function, must take in a string and return a
keys found in SHAREABLE_TEXT_LINE_*_KEYS used to access address details are placed dict. keys found in SHAREABLE_TEXT_LINE_*_KEYS used to access address details are placed
top-level in the dict, exceptions are handled by the caller. top-level in the dict, exceptions are handled by the caller.
see the [playground notebook](playground.ipynb) for example output see the [playground notebook](playground.ipynb) for example output
@ -645,7 +656,7 @@ values
### `class Result` ### `class Result`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing the result for safe value retrieval representing the result for safe value retrieval
attributes attributes
@ -667,10 +678,10 @@ def some_operation(path) -> Result[str]:
except Exception as exc: except Exception as exc:
# must pass a default value # must pass a default value
result = Result[str]("", error=exc) return Result[str]("", error=exc)
else: else:
result = Result[str](contents) return Result[str](contents)
# call function and handle result # call function and handle result
result = some_operation("some_file.txt") result = some_operation("some_file.txt")
@ -690,8 +701,8 @@ else:
methods methods
- [`def __bool__(self) -> bool: ...`](#result__bool__) - [`def __bool__(self) -> bool: ...`](#result__bool__)
- [`def get(self) -> ResultType: ...`](#resultcry) - [`def cry(self, string: bool = False) -> str: ...`](#resultcry)
- [`def cry(self, string: bool = False) -> str: ...`](#resultget) - [`def get(self) -> ResultType: ...`](#resultget)
#### `Result.__bool__()` #### `Result.__bool__()`
@ -737,7 +748,7 @@ method that returns `self.value` if Result is non-erroneous else raises error
### `class Latlong` ### `class Latlong`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing a latitude-longitude coordinate pair representing a latitude-longitude coordinate pair
attributes attributes
@ -764,7 +775,7 @@ method that returns a comma-and-space-seperated string of `self.latitude` and
### `class PlusCodeQuery` ### `class PlusCodeQuery`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing a full-length Plus Code (e.g., 6PH58QMF+FX) representing a full-length Plus Code (e.g., 6PH58QMF+FX)
attributes attributes
@ -807,7 +818,7 @@ method that returns string representation of query
### `class LocalCodeQuery` ### `class LocalCodeQuery`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing a representing a
[shortened Plus Code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening) [shortened Plus Code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening)
with locality, referred to by surplus as a "local code" with locality, referred to by surplus as a "local code"
@ -878,7 +889,7 @@ method that returns string representation of query
### `class LatlongQuery` ### `class LatlongQuery`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing a latitude-longitude coordinate pair representing a latitude-longitude coordinate pair
attributes attributes
@ -923,7 +934,7 @@ method that returns string representation of query
### `class StringQuery` ### `class StringQuery`
[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) [`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
representing a pure string query representing a pure string query
attributes attributes
@ -932,10 +943,10 @@ attributes
methods methods
- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#latlongqueryto_lat_long_coord) - [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#stringqueryto_lat_long_coord)
- [`def __str__(self) -> str: ...`](#latlongquery__str__) - [`def __str__(self) -> str: ...`](#stringquery__str__)
#### `LatlongQuery.to_lat_long_coord()` #### `StringQuery.to_lat_long_coord()`
method that returns a latitude-longitude coordinate pair method that returns a latitude-longitude coordinate pair
@ -954,7 +965,7 @@ method that returns a latitude-longitude coordinate pair
- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong) - returns [`Result`](#class-result)[`[Latlong]`](#class-latlong)
#### `LatlongQuery.__str__()` #### `StringQuery.__str__()`
method that returns string representation of query method that returns string representation of query
@ -1007,14 +1018,10 @@ function that parses a query string into a query object
default geocoder for surplus, uses OpenStreetMap Nominatim default geocoder for surplus, uses OpenStreetMap Nominatim
> **Note** > [!NOTE]
> function is not used by surplus and not directly by the user, but is exposed for > function is not used by surplus and not directly by the user, but is exposed for
> convenience > convenience being [Behaviour](#class-behaviour) objects.
> > pass in a custom function to [Behaviour](#class-behaviour) to override the default reverser.
> pass in a custom function to [Behaviour](#class-behaviour) to override the default
> reverser
>
> see [Behaviour](#class-behaviour) for more information on what the function does
- signature - signature
@ -1026,14 +1033,10 @@ default geocoder for surplus, uses OpenStreetMap Nominatim
default reverser for surplus, uses OpenStreetMap Nominatim default reverser for surplus, uses OpenStreetMap Nominatim
> **Note** > [!NOTE]
> function is not used by surplus and not directly by the user, but is exposed for > function is not used by surplus and not directly by the user, but is exposed for
> convenience > convenience being [Behaviour](#class-behaviour) objects.
> > pass in a custom function to [Behaviour](#class-behaviour) to override the default reverser.
> pass in a custom function to [Behaviour](#class-behaviour) to override the default
> reverser
>
> see [Behaviour](#class-behaviour) for more information on what the function does
- signature - signature
@ -1046,3 +1049,27 @@ default reverser for surplus, uses OpenStreetMap Nominatim
surplus is free and unencumbered software released into the public domain. for more surplus is free and unencumbered software released into the public domain. for more
information, please refer to the [UNLICENCE](/UNLICENCE), <https://unlicense.org>, or the information, please refer to the [UNLICENCE](/UNLICENCE), <https://unlicense.org>, or the
python module docstring. python module docstring.
however, direct dependencies of surplus are licensed under different, but still permissive
and open-source licences.
```text
geopy 2.4.0 Python Geocoding Toolbox
└── geographiclib >=1.52,<3
pluscodes 2022.1.3 Compute Plus Codes (Open Location Codes).
```
- [geopy](https://pypi.org/project/geopy/):
Python Geocoding Toolbox
MIT License
- [geographiclib](https://pypi.org/project/geographiclib/):
The geodesic routines from GeographicLib
MIT License
- [pluscodes](https://pypi.org/project/pluscodes/):
Compute Plus Codes (Open Location Codes)
Apache 2.0

5
pyproject.toml
View file

@ -32,9 +32,6 @@ line-length = 90
line_length = 90 line_length = 90
profile = "black" profile = "black"
[tool.setuptools.package-data]
"*" = ["py.typed"]
[build-system] [build-system]
requires = ["poetry-core",] requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api" build-backend = "poetry.core.masonry.api"

18
surplus/surplus.py
View file

@ -200,10 +200,10 @@ class Result(NamedTuple, Generic[ResultType]):
except Exception as exc: except Exception as exc:
# must pass a default value # must pass a default value
result = Result[str]("", error=exc) return Result[str]("", error=exc)
else: else:
result = Result[str](contents) return Result[str](contents)
# call function and handle result # call function and handle result
result = some_operation("some_file.txt") result = some_operation("some_file.txt")
@ -629,7 +629,9 @@ def parse_query(behaviour: Behaviour) -> Result[Query]:
) )
if behaviour.debug: if behaviour.debug:
behaviour.stderr.write(f"debug: {portion_plus_code=}, {portion_locality=}\n") behaviour.stderr.write(
f"debug: _match_plus_code: {portion_plus_code=}, {portion_locality=}\n"
)
return Result[Query]( return Result[Query](
LocalCodeQuery( LocalCodeQuery(
@ -654,7 +656,7 @@ def parse_query(behaviour: Behaviour) -> Result[Query]:
# Toa Payoh North (no commas) # Toa Payoh North (no commas)
if behaviour.debug: if behaviour.debug:
behaviour.stderr.write(f"debug: {behaviour.query=}\n") behaviour.stderr.write(f"debug: parse_query: {behaviour.query=}\n")
# check if empty # check if empty
if (behaviour.query == []) or (behaviour.query == ""): if (behaviour.query == []) or (behaviour.query == ""):
@ -914,7 +916,7 @@ def _generate_text(
] ]
if debug: if debug:
behaviour.stderr.write(f"debug: {seen_names=}\n") behaviour.stderr.write(f"debug: _generate_text: {seen_names=}\n")
general_global_info: list[str] = [ general_global_info: list[str] = [
str(location.get(detail, "")) for detail in st_line6_keys str(location.get(detail, "")) for detail in st_line6_keys
@ -984,7 +986,7 @@ def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]:
return Result[str]("", error=latlong.error) return Result[str]("", error=latlong.error)
if behaviour.debug: if behaviour.debug:
behaviour.stderr.write(f"debug: {latlong.get()=}\n") behaviour.stderr.write(f"debug: cli: {latlong.get()=}\n")
# reverse location and handle result # reverse location and handle result
try: try:
@ -994,7 +996,7 @@ def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]:
return Result[str]("", error=exc) return Result[str]("", error=exc)
if behaviour.debug: if behaviour.debug:
behaviour.stderr.write(f"debug: {location=}\n") behaviour.stderr.write(f"debug: cli: {location=}\n")
# generate text # generate text
if behaviour.debug: if behaviour.debug:
@ -1069,7 +1071,7 @@ def cli() -> int:
query = parse_query(behaviour=behaviour) query = parse_query(behaviour=behaviour)
if behaviour.debug: if behaviour.debug:
behaviour.stderr.write(f"debug: {query=}\n") behaviour.stderr.write(f"debug: cli: {query=}\n")
if not query: if not query:
behaviour.stderr.write(f"error: {query.cry(string=not behaviour.debug)}\n") behaviour.stderr.write(f"error: {query.cry(string=not behaviour.debug)}\n")