Metadata-Version: 2.1
Name: namsor-client
Version: 1.0.1
Summary: A Wrapper for the Namsor Classification API
Home-page: https://github.com/JosephPallipadan/Namsor-API-Wrapper-Python
Author: Joseph Pallipadan
Author-email: pallipadanjoseph@gmail.com
License: UNKNOWN
Description: ## Overview
        *namsor-client* is a python package that serves as a wrapper for the Namsor classification API.
        The API can determine the likely gender, ethnicity and country of origin of an individual with a particular name.
        
        ## Installation
        
        ```pip install namsor-client```
        
        ## Usage
        
        ```python
        from namsorclient import NamsorClient
        from namsorclient.country_codes import CountryCodes
        from namsorclient.request_objects import *
        
        
        # Create an instance of NamsorClient and pass in your API key as an argument.
        client = NamsorClient("Insert API key")
        
        # Access the gender (GET) endpoint with function that returns a response of type GenderResponse.
        response = client.gender("Lelouch","Lamperouge")
        
        # Access the different parts of the response for this particular endpoint.
        
        print(response.ID)
        print(response.first_name)
        print(response.last_name)
        print(response.likely_gender)
        print(response.gender_scale)
        print(response.score)
        print(response.probability_calibrated)
        
        # Refer to the Responses section to view all different variables of each different Response.
        
        
        # Access the genderBatch (POST) endpoint
        gender_batch = GenderBatch()
        
        # Add items, with required arguments, to the batch you want
        gender_batch.addItem("Lelouch","Lamperouge","A2773")
        gender_batch.addItem("Gon","Freecs", "M9835")
        gender_batch.addItem("Jonathan","Joestar", "M6104")
        
        # Use classify function with required API Key argument and receive responses in the form of a list.
        response_list = gender_batch.classify("Insert API key")
        
        print(response_list[2].likely_gender)
        
        # Refer to the Batches section to look at the different types of batches and view the type of responses that will be returned when a batch is classified.
        ```
        
        
        Use the `export_to_excel` function to create a file with the required file name to represent the batch's data in spreadsheet form. 
        ```python 
        gender_batch.export_to_excel("File Name.xlsx")
        ```
        **Result:**
        ![GitHub Logo](spreadsheet_example.png)
        ## API
        
        - **gender(first_name: str, last_name: str)**
        *Infer the likely gender of a name.*
        
            - ```first_name: The desired first name. ```
            - ```last_name: The desired last name. ```
            - *Returns*: ```GenderResponse ```
          
        - **genderGeo(first_name: str, last_name: str, country_code: CountryCodes)**
        *Infer the likely gender of a name, given a local context (ISO2country code).*
        
            - ```first_name: The desired first name.```
            - ```last_name: The desired last name.```
            - ```country_code: The country code to aid with classification.```
            - *Returns*: ```GenderResponse```
        
        - **genderFullGeo(full_name: str, country_code: CountryCodes)**
        *Infer the likely gender of a full name, given a local context (ISO2 country code).*
        
            - ```full_name: The name to be classified.```
            - ```country_code: The country code to aid with classification.```
            - *Returns*: ```GenderResponse```
        
        - **genderFull(full_name: str)**
        *Infer the likely gender of a full name, ex. John H. Smith*
        
            - ```full_name: The name to be classified.```
            - *Returns*: ```GenderResponse```
        
        - **usRaceEthnicity(first_name: str, last_name: str)**
        *Infer a US resident's likely race/ethnicity according to US Census taxonomy W_N(white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino).*
        
            - ```first_name: The desired first name.```
            - ```last_name: The desired last name.```
            - *Returns*: ```OriginResponse```
                
        - **usRaceEthnicityZIP5(first_name: str, last_name: str, zip5_code: str)**
        *Infer a US resident's likely race/ethnicity according to US Census taxonomy, usingZIP5code info. Output is W_NL (white, non latino), HL (hispano latino),  A (asian,non latino, B_NL (black, non latino).*
        
            - ```first_name: The desired first name```
            - ```last_name: The desired last name```
            - ```zip5_code: The zip code to aid with classification```
            - *Returns*: ```OriginResponse```
            
        
        - **diaspora(first_name: str, last_name: str, country_code: CountryCodes)**
        *Infer the likely ethnicity/diaspora of a personal name, given a country of residence ISO2 code*
        
            - ```first_name: The desired first name. ```
            - ```last_name: The desired last name. ```
            - ```country_code: The country code to aid with classification.```
            - *Returns*: ```DiasporaResponse ```
        
        - **parseName(full_name: str)**
        *Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John, given an ISO2 country of residence.*
        
            - ```full_name: The full name to be parsed. ```
            - *Returns*: ```ParseNameResponse ```
        
        - **parseNameGeo(full_name: str, country_code: CountryCodes)**
        *Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John, given an ISO2 country of residence.*
        
            - ```full_name: The full name to be parsed. ```
            - ```country_code: The country code to aid with classification.```
            - *Returns*: ```ParseNameResponse ```
        
        - **origin(first_name: str, last_name: str)**
        *Infer the likely country of origin of a personal name. Assumes names as they are in the country of origin. For US, CA, AU, NZ and other melting-pots : use 'diaspora' instead.*
        
            - ```first_name: The desired first name. ```
            - ```last_name: The desired last name. ```
            - *Returns*: ```OriginResponse ```
        
        - **country(full_name: str)**
        *Infer the likely country of residence of a personal full name, or one surname. Assumes names as they are in the country of residence OR the country of origin.*
        
            - ```full_name: The name whose country of residence should be determined. ```
            - *Returns*: ```OriginResponse ```
        
        
        
        ## Responses
        - **GenderResponse**
          - ```ID```
          - ```first_name```
          - ```last_name```
          - ```likely_gender```
          - ```gender_scale```
          - ```score```
          - ```probability_calibrated```
        - **GenderFullResponse**
          - ```ID```
          - ```name```
          - ```likely_gender```
          - ```gender_scale```
          - ```score```
        - **OriginResponse**
          - ```ID```
          - ```first_name```
          - ```last_name```
          - ```likely_gender```
          - ```score```
          - ```country_origin```
          - ```country_origin_alt```
          - ```region_origin```
          - ```top_region_origin```
          - ```sub_region_origin```
        - **CountryResponse**
          - ```ID```
          - ```name```
          - ```score```
          - ```country```
          - ```country_alt```
          - ```region```
          - ```top_region```
          - ```sub_region```
        - **RaceEthnicityResponse**
          - ```ID```
          - ```first_name```
          - ```last_name```
          - ```race_ethnicity```
          - ```race_ethnicity_alt```
          - ```score```
        - **DiasporaResponse**
          - ```ID```
          - ```first_name```
          - ```last_name```
          - ```score```
          - ```ethnicity```
          - ```ethnicity_alt```
          - ```lifted```
          - ```country```
        - **ParseNameResponse**
          - ```ID```
          - ```name```
          - ```name_parser_type```
          - ```name_parser_type_alt```
          - ```first_last_name```
          - ```score```
        
        ## Batches
        The wrapper also exposes batch functions for each of the different classifications. These are to be used when multiple items need to be classified together.
        
        - ```GenderBatch``` --> `classify` *function returns* `GenderResponse` *list*     
        - ```GenderGeoBatch``` -->  `classify` *function returns* `GenderResponse` *list*
        - ```ParsedGenderBatch``` --> `classify` *function returns* `GenderResponse` *list*
        - ```ParsedGenderGeoBatch``` --> `classify` *function returns* `GenderResponse` *list*
        - ```GenderFullBatch``` --> `classify` *function returns* `GenderFullResponse` *list*
        - ```GenderFullGeoBatch``` --> `classify` *function returns* `GenderFullResponse` *list*
        - ```OriginBatch``` --> `classify` *function returns* `OriginResponse` *list*
        - ```CountryBatch``` --> `classify` *function returns* `CountryResponse` *list*
        - ```US_RaceEthnicityBatch``` --> `classify` *function returns* `RaceEthnicityResponse` *list*
        - ```US_ZipRaceEthnicityBatch``` --> `classify` *function returns* `RaceEthnicityResponse` *list*
        - ```DiasporaBatch``` --> `classify` *function returns* `DiasporaResponse` *list*
        - ```ParseNameBatch``` --> `classify` *function returns* `ParsedNameResponse` *list*
        - ```ParseNameGeoBatch``` --> `classify` *function returns* `ParsedNameResponse` *list*
        
        
        ## Country Codes
        Whenever a country code needs to be passed to any function, the `CountryCodes` class should be used. It exposes an enum with all recognized country codes of the world marked by the respective country's name.
        
        ## Contributing
        To contribute to this repository, fork it and make changes. To run tests, cd into namsorclient and 
        run ```python -m pytest```. If all tests pass, sumbit a pull request. Note that the faker and xlrd modules are required for testing.
        
        
Keywords: Gender,Classify,Ethnicity,Origin,Country,Classifier,Namsor,Wrapper,Name to Gender,Name to Ethnicity,Name to Origin,Name
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
