Create python library for NameAPI Services

Author: g1ca

.gitignore

@@ -0,0 +1,79 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+.idea
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+
+# Unit test / coverage reports
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+.hypothesis/
+.pytest_cache/
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+.env
+.venv
+env/
+venv/
+env.bak/
+venv.bak/
+
+
+DevOps

README.md

@@ -0,0 +1,187 @@
+nameapi-client-python
+===================
+
+Python Client for the NameAPI Web Services at https://www.nameapi.org.
+
+There are functional tests that demonstrate how to use this library.
+
+All you need to send requests is your own api key which you can get from nameapi.org.
+
+This library requires at least Python 3.8.
+
+
+
+## Library setup
+
+Create virtual environment and activate it:
+
+    python -m venv myenv
+    myenv\Scripts\activate
+
+Install the required libraries:
+
+    pip install -r requirements.txt
+
+
+
+## Send a ping
+
+This code sends a simple ping to nameapi to test the connection:
+
+
+```python
+client = NameApiClient(None)
+response = client.ping() # return the string 'pong'
+```
+
+## Input / Output
+
+
+#### Person input object
+
+Most services accept a 'Person' as input. This person contains a name, and optionally
+more data such as gender, birth date etc.
+The name can be just a single "full name" string, or it can be composed of multiple
+fields like given name, middle name, surname.
+This standardized api makes it simple to use different services in a consistent way,
+and is very convenient in accepting the data however you have it at hands.
+
+Creating a simple person looks something like this:
+
+```python
+name_object = WesternInputPersonNameBuilder().fullname("Petra Müller").build()
+input_person = NaturalInputPersonBuilder().name(name_object).build()
+```
+
+Creating name objects:
+
+```python
+name_object_1 = WesternInputPersonNameBuilder() \
+    .fullname("Petra Müller") \
+    .build()
+
+name_object_2 = WesternInputPersonNameBuilder() \
+    .given_name("Petra") \
+    .surname("Müller") \
+    .build()
+
+name_object_3 = WesternInputPersonNameBuilder() \
+    .name_field(NameField("Petra", CommonNameFieldType.GIVENNAME)) \
+    .name_field(NameField("Müller", CommonNameFieldType.SURNAME)) \
+    .name_field(NameField("Alexa", AmericanNameFieldType.MIDDLENAME)) \
+    .build()
+
+name_object_4 = InputPersonName([NameField("petra müller", CommonNameFieldType.FULLNAME)])
+```
+
+Creating complex input person objects:
+
+```python
+input_person = NaturalInputPersonBuilder() \
+            .name(name_object_1) \
+            .gender(StoragePersonGender.MALE) \
+            .add_email("[email protected]") \
+            .add_tel_number("+5555555") \
+            .age(BirthDate(year=1999, month=2, day=1))\
+            .build()
+```
+
+#### Result objects
+
+Response from the requests, displayed as json: https://api.nameapi.org/rest/swagger-ui/
+
+Access the link above to see all the return type and their json format.
+
+
+## Commands
+
+The web service methods are implemented as commands. This brings the advantage that the
+command can be passed around and wrapped with other useful goodies such as logging
+in a unified way, without the need to put a wrapper around every service.
+For more specialized concerns such as auto-retry on failure this concept becomes
+a real advantage.
+
+
+
+## Name Parser
+
+Name parsing is the process of splitting a full name into its components.
+
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+response = client.person_name_parser(input_person_1)
+```
+
+
+## Name Genderizer
+
+Name genderizing is the process of identifying the gender based on a person's name.
+
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+response = client.person_genderizer(input_person_1)
+```
+
+
+## Name Matcher
+
+The Name Matcher compares names and name pairs to discover whether the people could possibly be one and the same person.
+
+This service takes 2 people as input:
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+response = client.person_matcher(input_person_1, input_person_2)
+```
+
+
+## Name Formatter
+
+The Name Formatter displays personal names in the desired form. This includes the order as well as upper and lower case writing.
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+response = client.person_name_formatter(input_person_1)
+```
+
+## Risk Detector
+
+Detects various types of possibly fake data in person records.
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+response = client.risk_detector(input_person_1)
+```
+
+
+
+## Email Name Parser
+
+The Email Name Parser extracts names out of email addresses.
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+email_address="[email protected]"
+response = client.email_name_parser(email_address)
+```
+
+
+## Disposable Email Address Detector
+
+The DEA-Detector checks email addresses against a list of known "trash domains" such as mailinator.com.
+
+```python
+api_key = None  # Set your api_key here
+client = NameApiClient(api_key)
+email_address="[email protected]"
+response = client.disposable_email_detector(email_address)
+```
+

nameapi_client/__init__.py

@@ -0,0 +1,50 @@
+from nameapi_client.command import DisposableEmailDetectorCommand, EmailNameParserCommand, \
+    PersonNameFormatterCommand, PersonGenderizerCommand, PersonMatcherCommand, PersonNameParserCommand, \
+    RiskDetectorCommand, PingCommand
+from nameapi_client.ontology.input_person import InputPerson
+from nameapi_client.services.email_parser import EmailDisposableResult, EmailNameParserResult
+from nameapi_client.services.person_formatter import FormatterResult
+from nameapi_client.services.person_genderizer import GenderizerResult
+from nameapi_client.services.person_matcher import PersonMatcherResult
+from nameapi_client.services.person_parser import PersonNameParserResult
+from nameapi_client.services.risk_detector import RiskDetectorResult
+
+
+class NameApiClient(object):
+    __cmd_disposable_email_detector = DisposableEmailDetectorCommand()
+    __cmd_email_name_parser = EmailNameParserCommand()
+    __cmd_person_name_formatter = PersonNameFormatterCommand()
+    __cmd_person_genderizer = PersonGenderizerCommand()
+    __cmd_person_matcher = PersonMatcherCommand()
+    __cmd_person_name_parser = PersonNameParserCommand()
+    __cmd_risk_detector = RiskDetectorCommand()
+    __cmd_ping = PingCommand()
+
+    def __init__(self, api_key: str):
+        self.__api_key = api_key
+
+    def disposable_email_detector(self, email_address: str) -> EmailDisposableResult:
+        return NameApiClient.__cmd_disposable_email_detector.execute(self.__api_key, email_address)
+
+    def email_name_parser(self, email_address: str) -> EmailNameParserResult:
+        return NameApiClient.__cmd_email_name_parser.execute(self.__api_key, email_address)
+
+    def person_name_formatter(self, person: InputPerson) -> FormatterResult:
+        return NameApiClient.__cmd_person_name_formatter.execute(self.__api_key, person)
+
+    def person_genderizer(self, person: InputPerson) -> GenderizerResult:
+        return NameApiClient.__cmd_person_genderizer.execute(self.__api_key, person)
+
+    def person_matcher(self, person1: InputPerson, person2: InputPerson) -> PersonMatcherResult:
+        return NameApiClient.__cmd_person_matcher.execute(self.__api_key, person1, person2)
+
+    def person_name_parser(self, person: InputPerson) -> PersonNameParserResult:
+        return NameApiClient.__cmd_person_name_parser.execute(self.__api_key, person)
+
+    def risk_detector(self, person: InputPerson) -> RiskDetectorResult:
+        return NameApiClient.__cmd_risk_detector.execute(self.__api_key, person)
+
+    def ping(self) -> str:
+        return NameApiClient.__cmd_ping.execute(self.__api_key)
+
+