v2.1.0 (#32)

* docs: remove self in SurplusReverserProtocol conforming signature

* docs: fix mismatching carets and add info on split_iso3166_2

* releaser: isort comply

* meta: bump version 2.1.0 -> 2.1.1

* meta: add dependabot

* alternative line 3 arrangement for IT/Italy (#31)

* tests: add alternative tp output

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

README.md

@@ -20,7 +20,7 @@ to iOS Shortcuts-like shareable text.
 
 ```text
 $ surplus 9R3J+R9 Singapore
-surplus version 2.1.0
+surplus version 2.1.1
 Thomson Plaza
 301 Upper Thomson Road
 Sin Ming, Bishan
@@ -260,12 +260,14 @@ of incorrect outputs.
 
 ```text
 $ s+ --debug 8QJF+RP Singapore
-surplus version 2.1.0, debug mode (latest@future, Tue 05 Sep 2023 23:38:59 +0800)
+surplus version 2.1.1, debug mode (latest@future, Tue 05 Sep 2023 23:38:59 +0800)
 debug: parse_query: behaviour.query=['8QJF+RP', 'Singapore']
 debug: _match_plus_code: portion_plus_code='8QJF+RP', portion_locality='Singapore'
 debug: cli: query=Result(value=LocalCodeQuery(code='8QJF+RP', locality='Singapore'), error=None)
 debug: latlong_result.get()=Latlong(latitude=1.3320625, longitude=103.7743125)
 debug: location={...}
+debug: _generate_text: split_iso3166_2=['SG', '03']
+debug: _generate_text: using special key arrangements for 'SG-03' (Singapore)
 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   --------  '535'
@@ -351,6 +353,17 @@ variables
   for more information on the reverser function, see
   [`SurplusReverserProtocol`](#surplusreverserprotocol)
 
+- **variable `split_iso3166_2` and special key arrangements**
+
+  a list of strings containing the split iso3166-2 code (country/subdivision identifier)
+
+  if special key arrangements are available for the code, a line similar to the following
+  will be shown:
+
+  ```text
+  debug: _generate_text: using special key arrangements for 'SG-03' (Singapore)
+  ```
+
 - **variable `seen_names`**
 
   a list of unique important names found in certain Nominatim keys used in final output
@@ -705,7 +718,7 @@ class for documentation and static type checking of surplus reverser functions
   functions that conform to this protocol should have the following signature:
 
   ```python
-  def example(self, latlong: Latlong, level: int = 18) -> dict[str, Any]: ...
+  def example(latlong: Latlong, level: int = 18) -> dict[str, Any]: ...
   ```
 
 - **information on conforming functions**
@@ -784,7 +797,7 @@ attributes
 
 > [!IMPORTANT]  
 > this has replaced the now deprecated default geocoding functions, `default_geocoder()`
-> and `default_reverser()`, in surplus 2.1.0 and later.
+> and `default_reverser()`, in surplus 2.1 and later.
 
 see [SurplusGeocoderProtocol](#surplusgeocoderprotocol) and
 [SurplusReverserProtocol](#surplusreverserprotocol) for more information how to
@@ -1275,7 +1288,7 @@ it contains the following, in order, alongside an example:
 1. `version` - the surplus version alongside a suffix, if any
 
    ```text
-   2.1.0-local
+   2.1.1-local
    ```
 
 2. `system_info` - generic machine and operating system information
@@ -1299,8 +1312,8 @@ it contains the following, in order, alongside an example:
 after hashing, this string becomes a 12 character hexadecimal string, as shown below:
 
 ```text
-surplus/2.1.0-local (1fdbfa0b0cfb)
+surplus/2.1.1-local (1fdbfa0b0cfb)
-                     ^^^^^^^^^^
+                     ^^^^^^^^^^^^
                      this is the hashed result of unique_info
 ```
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "surplus"
-version = "2.1.0"
+version = "2.1.1"
 description = "Python script to convert Google Maps Plus Codes to iOS Shortcuts-like shareable text."
 authors = ["Mark Joshwel <mark@joshwel.co>"]
 license = "Unlicense"

releaser.py

@@ -34,7 +34,6 @@ from os import getenv
 from pathlib import Path
 from subprocess import run
 
-
 # NOTE: change this if surplus has moved
 path_surplus = Path(__file__).parent.joinpath("./surplus/surplus.py")
 

surplus/surplus.py

@@ -68,7 +68,7 @@ from pluscodes.openlocationcode import (  # type: ignore # isort: skip
 
 # constants
 
-VERSION: Final[tuple[int, int, int]] = (2, 1, 0)
+VERSION: Final[tuple[int, int, int]] = (2, 1, 1)
 VERSION_SUFFIX: Final[str] = "-local"
 BUILD_BRANCH: Final[str] = "future"
 BUILD_COMMIT: Final[str] = "latest"
@@ -101,11 +101,19 @@ SHAREABLE_TEXT_LINE_0_KEYS: Final[tuple[str, ...]] = (
 )
 SHAREABLE_TEXT_LINE_1_KEYS: Final[tuple[str, ...]] = ("building",)
 SHAREABLE_TEXT_LINE_2_KEYS: Final[tuple[str, ...]] = ("highway",)
+
 SHAREABLE_TEXT_LINE_3_KEYS: Final[tuple[str, ...]] = (
     "house_number",
     "house_name",
     "road",
 )
+# special line 3 keys for Italian addresses (IT)
+SHAREABLE_TEXT_LINE_3_KEYS_IT: Final[tuple[str, ...]] = (
+    "road",
+    "house_number",
+    "house_name",
+)
+
 SHAREABLE_TEXT_LINE_4_KEYS: Final[tuple[str, ...]] = (
     "residential",
     "neighbourhood",
@@ -1223,6 +1231,7 @@ def _generate_text(
     st_names = SHAREABLE_TEXT_NAMES
     st_locality: tuple[str, ...] = ()
 
+    # special key arrangements for edge cases in local/regional address formats
     match split_iso3166_2:
         case ["SG", *_]:  # Singapore
             if debug:
@@ -1232,7 +1241,17 @@ def _generate_text(
                     file=behaviour.stderr,
                 )
 
-            st_locality = SHAREABLE_TEXT_LOCALITY["SG"]
+            st_locality = SHAREABLE_TEXT_LOCALITY[split_iso3166_2[0]]
+
+        case ["IT", *_]:  # Italy
+            if debug:
+                print(
+                    "debug: _generate_text: "
+                    f"using special key arrangements for '{iso3166_2}' (Italy)",
+                    file=behaviour.stderr,
+                )
+
+            st_line3_keys = SHAREABLE_TEXT_LINE_3_KEYS_IT
 
         case _:  # default
             if debug:

test.py

@@ -130,7 +130,13 @@ tests: list[ContinuityTest] = [
                 "Tampines West\n"
                 "529757\n"
                 "Northeast, Singapore"
-            )
+            ),
+            (
+                "Temasek Polytechnic\n"
+                "21 Tampines Avenue 1\n"
+                "529757\n"
+                "Southeast, Singapore"
+            ),
         ],
     ),
 ]