pyconvertu 0.4.1__tar.gz → 1.0.0__tar.gz

pyconvertu-1.0.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pyconvertu
+Version: 1.0.0
+Summary: From/to Classification Converter
+Author-email: The Economist <29724411+econcz@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/econcz/pyconvertu
+Project-URL: Bug Tracker, https://github.com/econcz/pyconvertu/issues
+Keywords: data-science,classification,converter,iso-3166-1,iso-3166-1-alpha-3,iso-3166-1-alpha-2,iso-3166-1-numeric
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# CONVERTU - From/to Classification Converter
+
+Tools for creating and converting between classification systems.
+
+## Installation
+
+```bash
+pip install pyconvertu
+```
+
+## Quick example
+python:  
+```python
+from pyconvertu import convert
+
+print(convert(to="iso3", text=["Czech Republic", "Slovakia"]))
+```
+bash:  
+```bash
+uconv -t iso3 'Czech Republic' 'Slovakia'
+echo -e "Czech Republic\nSlovakia" | uconv -t iso3
+```
+
+## User Reference
+
+```python
+convert(
+    data=[...], json_file='...', info=False, dump=False,
+    to="...", text="..." | ["...", "..."], *args, **kwargs
+)
+```
+
+Convert text into a target classification using a JSON mapping, or return mapping/metadata (info/dump modes).
+
+**Parameters:**  
+
+`data` : *list[dict]*, optional  
+A complete classification mapping provided directly as a list of dictionaries. If supplied without `json_file`, this data will be used in-memory for conversions without reading from disk.
+
+`json_file` : *str*, optional  
+Path to the classification JSON file. If not provided, the default bundled `classification.json` is used. When `data` is not supplied, this file is loaded and used as the source mapping. When `data` is supplied along with `json_file`, the data is written to `json_file`.
+
+`info` : *bool*, default = *False*  
+If *True*, return only metadata/sources entries. No conversion.
+
+`dump` : *bool*, default = *False*  
+If *True*, return the full mapping (filtered of metadata/sources). No conversion.
+
+`to` : *str*  
+Target field name to return from matched records (e.g., "iso3").
+
+`text` : *str* | *list[str]*  
+One string or a list of strings to convert. A single string input yields a single string output; a list yields a list.
+
+**Classification passed via `data`**
+
+The JSON must follow the same structure as the bundled classification.json.
+
+```
+[
+    {
+        "regex":    "^(.*afgh.*|\\s*AFG\\s*|\\s*AF\\s*|\\s*4\\s*)$",
+        "name_en":  "Afghanistan",
+        "name_fr":  "Afghanistan (l')",
+        "iso3":     "AFG",
+        "iso2":     "AF",
+        "isoN":     "4"
+    },
+    ...
+    {
+        "metadata": {
+            "name_en": "English short name",
+            "name_fr": "French short name",
+            "iso3": "alpha-3 code",
+            "iso2": "alpha-2 code",
+            "isoN": "numeric"
+        }
+    },
+    {
+        "sources": [
+            "[https://www.iso.org/iso-3166-country-codes.html](ISO 3166 COUNTRY CODES)",
+            "[https://en.wikipedia.org/wiki/List_of_alternative_country_names](ALTERNATIVE NAMES)"
+        ]
+    }
+]
+```
+
+## License
+
+MIT License — see the [LICENSE](LICENSE) file.

pyconvertu-1.0.0/README.md

@@ -0,0 +1,90 @@
+# CONVERTU - From/to Classification Converter
+
+Tools for creating and converting between classification systems.
+
+## Installation
+
+```bash
+pip install pyconvertu
+```
+
+## Quick example
+python:  
+```python
+from pyconvertu import convert
+
+print(convert(to="iso3", text=["Czech Republic", "Slovakia"]))
+```
+bash:  
+```bash
+uconv -t iso3 'Czech Republic' 'Slovakia'
+echo -e "Czech Republic\nSlovakia" | uconv -t iso3
+```
+
+## User Reference
+
+```python
+convert(
+    data=[...], json_file='...', info=False, dump=False,
+    to="...", text="..." | ["...", "..."], *args, **kwargs
+)
+```
+
+Convert text into a target classification using a JSON mapping, or return mapping/metadata (info/dump modes).
+
+**Parameters:**  
+
+`data` : *list[dict]*, optional  
+A complete classification mapping provided directly as a list of dictionaries. If supplied without `json_file`, this data will be used in-memory for conversions without reading from disk.
+
+`json_file` : *str*, optional  
+Path to the classification JSON file. If not provided, the default bundled `classification.json` is used. When `data` is not supplied, this file is loaded and used as the source mapping. When `data` is supplied along with `json_file`, the data is written to `json_file`.
+
+`info` : *bool*, default = *False*  
+If *True*, return only metadata/sources entries. No conversion.
+
+`dump` : *bool*, default = *False*  
+If *True*, return the full mapping (filtered of metadata/sources). No conversion.
+
+`to` : *str*  
+Target field name to return from matched records (e.g., "iso3").
+
+`text` : *str* | *list[str]*  
+One string or a list of strings to convert. A single string input yields a single string output; a list yields a list.
+
+**Classification passed via `data`**
+
+The JSON must follow the same structure as the bundled classification.json.
+
+```
+[
+    {
+        "regex":    "^(.*afgh.*|\\s*AFG\\s*|\\s*AF\\s*|\\s*4\\s*)$",
+        "name_en":  "Afghanistan",
+        "name_fr":  "Afghanistan (l')",
+        "iso3":     "AFG",
+        "iso2":     "AF",
+        "isoN":     "4"
+    },
+    ...
+    {
+        "metadata": {
+            "name_en": "English short name",
+            "name_fr": "French short name",
+            "iso3": "alpha-3 code",
+            "iso2": "alpha-2 code",
+            "isoN": "numeric"
+        }
+    },
+    {
+        "sources": [
+            "[https://www.iso.org/iso-3166-country-codes.html](ISO 3166 COUNTRY CODES)",
+            "[https://en.wikipedia.org/wiki/List_of_alternative_country_names](ALTERNATIVE NAMES)"
+        ]
+    }
+]
+```
+
+## License
+
+MIT License — see the [LICENSE](LICENSE) file.

pyconvertu-1.0.0/convertu/__init__.py

@@ -0,0 +1,8 @@
+__version__ = "1.0.0"
+
+from .datau import autorun
+
+__all__ = [
+	"convert",
+	"__version__"
+]

pyconvertu-1.0.0/convertu/__main__.py

@@ -0,0 +1,96 @@
+from   __future__  import annotations
+import signal
+import sys
+import argparse
+from   pyconvertu  import convert, __version__
+from   typing      import Any
+from   json        import dumps
+
+def _print_human_readable(obj: Any) -> None:
+    """
+    Pretty-print JSON-like Python objects with UTF-8 characters preserved.
+    """
+    print(dumps(obj, ensure_ascii=False, indent=2))
+
+def main() -> int:
+    # make SIGPIPE behave like a normal EOF on Unix
+    if hasattr(signal, "SIGPIPE"):
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+      
+    # prefer UTF-8 on stdout for consistent output
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+    parser = argparse.ArgumentParser(
+        description="Convert from/to the desired classification."
+    )
+    parser.add_argument(
+        "-v", "--version", action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show version and exit."
+    )
+    parser.add_argument(
+        "-s", "--source", dest="source", default=None, metavar="PATH",
+        help="Path to the classification JSON file (default: bundled file)."
+    )
+    parser.add_argument(
+        "-t", "--to", dest="to", default=None, metavar="FIELD",
+        help="E.g., iso3, iso2, name_en (Required unless --info/--dump)."
+    )
+    parser.add_argument(
+        "--info", action="store_true",
+        help="Show metadata and sources in human-readable form."
+    )
+    parser.add_argument(
+        "--dump", action="store_true",
+        help="Show the classification records in human-readable form."
+    )
+    parser.add_argument(
+        "text", nargs="*",
+        help="Input text(s) to convert (e.g., uconv -t iso3 'Czech Republic')."
+    )
+    try:
+        args = parser.parse_args()
+        if args.info:
+            result = convert(json_file=args.source, info=True)
+            _print_human_readable(result)
+            return 0
+        if args.dump:
+            result = convert(json_file=args.source, dump=True)
+            _print_human_readable(result)
+            return 0
+        if not args.to:
+            print("error: --to/-t is required unless using --info or --dump",
+                  file=sys.stderr)
+            return 1
+    
+        # if no positional args, try reading from stdin (one item per line)
+        inputs = list(args.text)
+        if not inputs and not sys.stdin.isatty():
+            inputs = [line.strip() for line in sys.stdin if line.strip()]
+        if not inputs:
+            print("error: provide at least one input text (args or STDIN)",
+                  file=sys.stderr)
+            return 1
+
+        # preserve shape: single token -> str, multiple -> list[str]
+        text_in: str | list[str] = inputs[0] if len(inputs) == 1 else inputs
+        result = convert(json_file=args.source, to=args.to, text=text_in)
+        if isinstance(result, list):
+            for item in result:
+                print(item)
+        else:
+            print(result)
+        return 0
+    except BrokenPipeError:
+        try:
+          sys.stdout.close()
+        finally:
+          return 0
+    except KeyboardInterrupt:
+          return 130
+
+if __name__ == "__main__":
+    sys.exit(main())

pyconvertu-1.0.0/convertu/convertu.py

@@ -0,0 +1,198 @@
+import sys
+from   os     import path
+from   re     import compile, Pattern, I, M, error as RegexError
+from   typing import Any
+from   json   import load, dump as save, JSONDecodeError
+
+class ConvertUError(Exception):
+    """
+    Exception class for ConvertU-related errors.
+
+    Raised when an error occurs during classification conversion,
+    metadata retrieval, or parsing of external JSON files.
+    Provides structured messaging and optional diagnostic tagging.
+
+    Parameters
+    ----------
+    message : str, optional
+        Human-readable description of the error. Defaults to a generic message.
+
+    code : int or str, optional
+        Optional error code or identifier for structured handling.
+
+    Usage
+    -----
+    raise ConvertUError("Unsupported classification key", code=400)
+    """
+    def __init__(self, message: str       = "An error occurred in convertu",
+                       code:    int | str | None = None):
+        self.message = message
+        self.code    = code
+        full_message = f"{message} (Code: {code})" if code is not None         \
+                                                   else message
+        super().__init__(full_message)
+        
+    def __str__(self) -> str:
+        return self.message if self.code is None                               \
+                            else f"{self.message} [Code: {self.code}]"
+    
+    def as_dict(self) -> dict:
+        return {"error": self.message, "code": self.code}
+
+def _default_json_path() -> str:
+    """
+    Resolve the default path to the bundled `classification.json` file.
+    """
+    try:
+        base = sys.modules['pyconvertu'].__file__
+    except KeyError:
+        base = __file__
+    return path.join(path.dirname(base), r'classification.json')
+
+def _validate_data(obj: list[dict[str, Any]]) -> None:
+    """
+    Validate that `obj` conforms to the required structure:
+    - at least one dict has key 'regex'    (value is a str );
+    - exactly  one dict has key 'metadata' (value is a dict);
+    - exactly  one dict has key 'sources'  (value is a list).
+    """
+    if not isinstance(obj, list) or not all(isinstance(d, dict) for d in obj):
+        raise  ConvertUError("obj must be a list[dict]")
+    if not any(isinstance(d.get("regex"), str) and d.get("regex", "").strip()
+             for d in obj):
+        raise  ConvertUError("obj must include at least one entry with "
+                             "a non-empty 'regex' string")
+    if sum(1 for d in obj if "metadata" in d                    and
+                             isinstance(d["metadata"], dict)    and
+                             d["metadata"])                     != 1:
+        raise  ConvertUError("obj must include exactly one non-empty "
+                             "'metadata' dict")
+    if sum(1 for d in obj if "sources"  in d                    and
+                             isinstance(d["sources"], list)     and
+                             d["sources"])                      != 1:
+        raise  ConvertUError("obj must include exactly one non-empty "
+                             "'sources' list")
+
+def convert(
+    data: list[dict] | None = None,  json_file: str             | None = None,
+    info: bool              = False, dump:      bool                   = False,
+    to:   str               = '',    text:      str | list[str] | None = None,
+    *args, **kwargs
+) -> str | list[str] | list[dict]:
+    """
+    Convert text into a target classification using a JSON mapping, or
+    return mapping/metadata (info/dump modes).
+
+    Parameters
+    ----------
+    data : list[dict], optional
+        A complete classification mapping provided directly as a list of
+        dictionaries. If supplied without `json_file`, this data will be
+        used in-memory for conversions without reading from disk.
+
+    json_file : str, optional
+        Path to the classification JSON file. If not provided, the default
+        bundled `classification.json` is used. When `data` is not supplied,
+        this file is loaded and used as the source mapping. When `data` is
+        supplied along with `json_file`, the data is written to `json_file`.
+
+    info : bool, default = False
+        If True, return only metadata/sources entries. No conversion.
+
+    dump : bool, default = False
+        If True, return the full mapping (filtered of metadata/sources).
+        No conversion.
+
+    to : str
+        Target field name to return from matched records (e.g., "iso3").
+
+    text : str | list[str]
+        One string or a list of strings to convert. A single string input
+        yields a single string output; a list yields a list.
+
+    Returns
+    -------
+    str | list[str] | list[dict]
+        - If `info=True`: list of metadata/sources dicts.
+        - If `dump=True`: list of mapping dicts (no metadata/sources).
+        - Otherwise: converted string(s). If no match is found, the original
+          value is returned. If `text` is None, returns an empty list.
+    """
+    # retrieve the metadata/sources and classification
+    if data is not None:                               # read from the argument
+        _validate_data(data)
+        if  json_file is not None:
+            json_file = path.expanduser(json_file)
+            try:
+                with open(json_file, "w", encoding="utf-8") as f:
+                    save(data, f, ensure_ascii=False, indent=2)
+            except OSError as e:
+                raise ConvertUError(f"Unable to write to {json_file}: {e}")
+            return json_file
+    else:                                              # read from the file
+        if  json_file is None:
+            json_file = path.expanduser(_default_json_path())
+        if  not path.isfile(json_file):
+            raise ConvertUError(f"Classification file not found: {json_file}")
+        try:
+            with open(json_file, encoding="utf-8") as f:
+                data = load(f)
+        except JSONDecodeError as e:
+            raise ConvertUError(f"Invalid JSON in {json_file}: {e}")
+        except OSError as e:
+            raise ConvertUError(f"Unable to read {json_file}: {e}")
+        if  not isinstance(data, list):
+            raise ConvertUError("Mapping JSON must be a list of objects")
+    metadata                             = [
+        d for d in data
+        if isinstance(d, dict) and ('metadata'     in d or
+                                    'sources'      in d)
+    ]
+    classification: list[dict[str, Any]] = [
+        d for d in data
+        if isinstance(d, dict) and ('metadata' not in d and
+                                    'sources'  not in d)
+    ]
+
+    # return metadata/sources or classification
+    if  info:
+        return metadata                                # return metadata
+    if  dump:
+        return classification                          # return classification
+
+    # process arguments
+    if   text is None:
+        items: list[str] = []
+        single_input = False
+    elif isinstance(text, str):
+        items = [text]
+        single_input = True
+    elif isinstance(text, list) and all(isinstance(s, str) for s in text):
+        items = text
+        single_input = False
+    else:
+        raise ConvertUError("text must be str, list[str], or None")
+
+    # precompile regex patterns once
+    compiled: list[tuple[Pattern[str], dict[str, Any]]] = []
+    for r in classification:
+        p = r.get('regex')
+        if  to in r and isinstance(p, str) and p:
+            try:
+                compiled.append((compile(p, I | M), r))
+            except RegexError:
+                continue
+    if  items and not compiled:
+        return text if single_input else items
+
+    # convert compiled
+    def convert_one(s: str) -> str:
+        s = str(s)
+        for p, r in compiled:
+            if  p.search(s):
+                val = r.get(to)
+                return s if val is None else val       # return converted text
+        return s                                       # return original  text
+
+    result = [convert_one(s) for s in items]
+    return result[0] if single_input else result

pyconvertu-1.0.0/pyconvertu.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pyconvertu
+Version: 1.0.0
+Summary: From/to Classification Converter
+Author-email: The Economist <29724411+econcz@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/econcz/pyconvertu
+Project-URL: Bug Tracker, https://github.com/econcz/pyconvertu/issues
+Keywords: data-science,classification,converter,iso-3166-1,iso-3166-1-alpha-3,iso-3166-1-alpha-2,iso-3166-1-numeric
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# CONVERTU - From/to Classification Converter
+
+Tools for creating and converting between classification systems.
+
+## Installation
+
+```bash
+pip install pyconvertu
+```
+
+## Quick example
+python:  
+```python
+from pyconvertu import convert
+
+print(convert(to="iso3", text=["Czech Republic", "Slovakia"]))
+```
+bash:  
+```bash
+uconv -t iso3 'Czech Republic' 'Slovakia'
+echo -e "Czech Republic\nSlovakia" | uconv -t iso3
+```
+
+## User Reference
+
+```python
+convert(
+    data=[...], json_file='...', info=False, dump=False,
+    to="...", text="..." | ["...", "..."], *args, **kwargs
+)
+```
+
+Convert text into a target classification using a JSON mapping, or return mapping/metadata (info/dump modes).
+
+**Parameters:**  
+
+`data` : *list[dict]*, optional  
+A complete classification mapping provided directly as a list of dictionaries. If supplied without `json_file`, this data will be used in-memory for conversions without reading from disk.
+
+`json_file` : *str*, optional  
+Path to the classification JSON file. If not provided, the default bundled `classification.json` is used. When `data` is not supplied, this file is loaded and used as the source mapping. When `data` is supplied along with `json_file`, the data is written to `json_file`.
+
+`info` : *bool*, default = *False*  
+If *True*, return only metadata/sources entries. No conversion.
+
+`dump` : *bool*, default = *False*  
+If *True*, return the full mapping (filtered of metadata/sources). No conversion.
+
+`to` : *str*  
+Target field name to return from matched records (e.g., "iso3").
+
+`text` : *str* | *list[str]*  
+One string or a list of strings to convert. A single string input yields a single string output; a list yields a list.
+
+**Classification passed via `data`**
+
+The JSON must follow the same structure as the bundled classification.json.
+
+```
+[
+    {
+        "regex":    "^(.*afgh.*|\\s*AFG\\s*|\\s*AF\\s*|\\s*4\\s*)$",
+        "name_en":  "Afghanistan",
+        "name_fr":  "Afghanistan (l')",
+        "iso3":     "AFG",
+        "iso2":     "AF",
+        "isoN":     "4"
+    },
+    ...
+    {
+        "metadata": {
+            "name_en": "English short name",
+            "name_fr": "French short name",
+            "iso3": "alpha-3 code",
+            "iso2": "alpha-2 code",
+            "isoN": "numeric"
+        }
+    },
+    {
+        "sources": [
+            "[https://www.iso.org/iso-3166-country-codes.html](ISO 3166 COUNTRY CODES)",
+            "[https://en.wikipedia.org/wiki/List_of_alternative_country_names](ALTERNATIVE NAMES)"
+        ]
+    }
+]
+```
+
+## License
+
+MIT License — see the [LICENSE](LICENSE) file.

pyconvertu-1.0.0/pyconvertu.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+convertu/__init__.py
+convertu/__main__.py
+convertu/convertu.py
+pyconvertu.egg-info/PKG-INFO
+pyconvertu.egg-info/SOURCES.txt
+pyconvertu.egg-info/dependency_links.txt
+pyconvertu.egg-info/entry_points.txt
+pyconvertu.egg-info/top_level.txt

pyconvertu-1.0.0/pyconvertu.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uconv = pyconvertu.__main__:main

pyconvertu-1.0.0/pyconvertu.egg-info/top_level.txt

@@ -0,0 +1 @@
+convertu

pyconvertu-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "pyconvertu"
+version = "1.0.0"
+description = "From/to Classification Converter"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "The Economist", email = "29724411+econcz@users.noreply.github.com" }
+]
+keywords = [
+  "data-science",
+  "classification",
+  "converter",
+  "iso-3166-1",
+  "iso-3166-1-alpha-3",
+  "iso-3166-1-alpha-2",
+  "iso-3166-1-numeric"
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Information Analysis"
+]
+dependencies = []
+
+[project.scripts]
+uconv = "pyconvertu.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/econcz/pyconvertu"
+"Bug Tracker" = "https://github.com/econcz/pyconvertu/issues"
+
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["convertu"]
+
+[tool.setuptools.package-data]
+pyconvertu = ["classification.json"]

pyconvertu-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyconvertu-0.4.1/LICENSE.txt

@@ -1,7 +0,0 @@
-Copyright 2021 econcz
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.