| Name | namefully JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A Python utility for handling person names in a particular order, way, or shape. |
| upload_time | 2024-11-24 05:34:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
format
name
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# namefully
[![PyPI version][version-img]][version-url]
[![Downloads][downloads-img]][version-url]
[![CI build][ci-img]][ci-url]
[![License][license-img]][license-url]
Name handling made easy.
## Installation
```bash
pip install namefully
```
> **Note**: Python 3.7+ is required.
## Usage
```python
>>> from namefully import Namefully
>>> name = Namefully('Thomas Alva Edison')
>>> name.short
'Thomas Edison'
>>> name.public
'Thomas E'
>>> name.initials(with_mid=True)
['T', 'A', 'E']
>>> name.format('L, f m')
'EDISON, Thomas Alva'
>>> name.zip()
'Thomas A. E.'
```
> **NOTE**: if you intend to use this utility for non-standard name cases such as
> many middle names or last names, some extra work is required. For example,
> using `Namefully.parse()` lets you parse names containing many middle names
> with the risk of throwing a `NameError` when the parsing is not possible.
See [examples] or [test cases] for more details.
## Additional Settings
Below are enlisted additional settings supported by `namefully`. Use the following
keyword arguments to customize the output of the name parts.
### ordered_by
`first_name | last_name` - default: `first_name`
`ordered_by` specifies the order of name pieces when provided as raw string values
or string array values.
```python
>>> from namefully import Namefully
>>> name = Namefully('Smith John Joe', ordered_by='last_name')
>>> name.last
'Smith'
>>> name = Namefully(['Edison', 'Thomas'], ordered_by='last_name')
>>> name.first
'Thomas'
```
> **Note**: The order of appearance set initially will be prioritized in other
> operations. However, it can be adjusted dynamically as needed. See the example below.
```python
>>> from namefully import Namefully
>>> name = Namefully('Smith John Joe', ordered_by='last_name')
>>> name.full
'Smith John Joe'
>>> name.full_name(ordered_by='first_name')
'John Joe Smith'
```
### separator
`'' | , | : | " | - | . | ; | ' | ' ' | _]` - default: `' '` (white space)
Supported separators are: empty, comma, colon, double quotes, hyphen, period,
semicolon, single quote, white space, and underscore.
Though _only valid for raw string values_, `separator` indicates how to split the
parts of a raw string name under the hood. If you want more control, use a custom
`Parser`.
```python
>>> from namefully import Namefully
>>> name = Namefully('John,Smith', separator=',')
>>> name.full
'John Smith'
```
### title
`uk | us` - default: `uk`
`title` abides by the ways the international community defines an abbreviated title.
American and Canadian English follow slightly different rules for abbreviated
titles than British and Australian English. In North American English, titles
before a name require a period: `Mr., Mrs., Ms., Dr.`. In British and Australian
English, no periods are used in these abbreviations.
```python
>>> from namefully import Namefully
>>> name = Namefully.only(prefix='Mr', first='John', last='Smith', title='us')
>>> name.full
'Mr. John Smith'
>>> name.prefix
'Mr.'
```
### ending
`bool` - default: `False`
This sets an ending character after the full name (a comma before the suffix actually).
```python
>>> from namefully import Namefully
>>> name = Namefully.only('John', 'Smith', suffix='PhD', ending=True)
>>> name.full
'John Smith, PhD'
>>> name.suffix
'PhD'
```
### surname
`father | mother | hyphenated | all` - default: `father`
`surname` defines the distinct formats to output a compound surname (e.g., Hispanic surnames).
```python
>>> from namefully import Namefully, FirstName, LastName
>>> name = Namefully([FirstName('John'), LastName('Doe', 'Smith')], surname='hyphenated')
>>> name.full
'John Doe-Smith'
```
### bypass
`bool` - default: `True`
This will bypass all the built-in validators (i.e., validation rules, regular expressions).
```python
>>> from namefully import Namefully
>>> name = Namefully.only('Jane', 'Smith', suffix='M.Sc', bypass=False)
Traceback (most recent call last):
...
ValidationError (suffix='M.Sc'): invalid content
```
To sum it all up, the default values are:
```python
>>> from namefully import Config
>>> config = Config.create()
>>> config
<Config: default>
>>> config.to_dict()
{'name': 'default', 'ordered_by': 'first_name', 'separator': ' ', 'title': 'uk', 'ending': False, 'bypass': False, 'surname': 'father'}
```
## Do It Yourself
Customize your own parser to indicate the full name yourself.
```python
from namefully import Namefully, Parser, FullName
class SimpleParser(Parser):
def parse(self, **options) -> FullName:
fn, ln = self.raw.split('#')
return FullName.parse({'first_name': fn, 'last_name': ln}, **options)
name = Namefully(SimpleParser('Juan#Garcia'))
print(name.full) # Juan Garcia
```
## Concepts and examples
The name standards used for the current version of this library are as follows:
`[prefix] first_name [middle_name] last_name [suffix]`
The opening `[` and closing `]` brackets mean that these parts are optional. In
other words, the most basic/typical case is a name that looks like this:
`John Smith`, where `John` is the _firstName_ and `Smith`, the _lastName_.
> **NOTE**: Do note that the order of appearance matters and (as shown in [ordered_by](#ordered_by))
> can be altered through configured parameters. By default, the order of appearance
> is as shown above and will be used as a basis for future examples and use cases.
### Basic cases
Let us take a common example:
`Mr John Joe Smith PhD`
So, this utility understands the name parts as follows:
- prefix: `Mr`
- first name: `John`
- middle name: `Joe`
- last name: `Smith`
- suffix: `PhD`
- full name: `Mr John Joe Smith PhD`
- birth name: `John Joe Smith`
- short version: `John Smith`
- flattened: `John J. S.`
- initials: `J J S`
- public: `John S`
- salutation: `Mr Smith`
### Limitations
`namefully` does not support certain use cases:
- mononame: `Plato` - a workaround is to set the mononame as both first and last name;
- multiple prefixes or suffixes: `Prof. Dr. Einstein`.
## Contributing
Visit [CONTRIBUTING.md][contributing-url] for details on the contribution guidelines,
the code of conduct, and the process for submitting pull requests.
## License
The underlying content of this utility is licensed under [MIT][license-url].
<!-- References -->
[version-img]: https://img.shields.io/pypi/v/namefully
[version-url]: https://pypi.python.org/pypi/namefully
[license-img]: https://img.shields.io/pypi/l/namefully
[license-url]: https://github.com/ralflorent/namefully-python/blob/main/LICENSE
[downloads-img]: https://img.shields.io/pypi/dm/namefully
[ci-img]: https://github.com/ralflorent/namefully-python/workflows/Build/badge.svg
[ci-url]: https://github.com/ralflorent/namefully-python/actions/workflows/build.yml
[contributing-url]: https://github.com/ralflorent/namefully-python/blob/main/CONTRIBUTING.md
[examples]: https://github.com/ralflorent/namefully-python/blob/main/examples/main.py
[test cases]:https://github.com/ralflorent/namefully-python/blob/main/test
Raw data
{
"_id": null,
"home_page": null,
"name": "namefully",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "format, name",
"author": null,
"author_email": "Ralph Florent <ralflornt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/15/e0/b2faf5b73d924f59f50ef6274c88a04f32632c609c22bbf0461d08224180/namefully-1.0.0.tar.gz",
"platform": null,
"description": "# namefully\n\n[![PyPI version][version-img]][version-url]\n[![Downloads][downloads-img]][version-url]\n[![CI build][ci-img]][ci-url]\n[![License][license-img]][license-url]\n\nName handling made easy.\n\n## Installation\n\n```bash\npip install namefully\n```\n\n> **Note**: Python 3.7+ is required.\n\n## Usage\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully('Thomas Alva Edison')\n>>> name.short\n'Thomas Edison'\n>>> name.public\n'Thomas E'\n>>> name.initials(with_mid=True)\n['T', 'A', 'E']\n>>> name.format('L, f m')\n'EDISON, Thomas Alva'\n>>> name.zip()\n'Thomas A. E.'\n```\n\n> **NOTE**: if you intend to use this utility for non-standard name cases such as\n> many middle names or last names, some extra work is required. For example,\n> using `Namefully.parse()` lets you parse names containing many middle names\n> with the risk of throwing a `NameError` when the parsing is not possible.\n\nSee [examples] or [test cases] for more details.\n\n## Additional Settings\n\nBelow are enlisted additional settings supported by `namefully`. Use the following\nkeyword arguments to customize the output of the name parts.\n\n### ordered_by\n\n`first_name | last_name` - default: `first_name`\n\n`ordered_by` specifies the order of name pieces when provided as raw string values\nor string array values.\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully('Smith John Joe', ordered_by='last_name')\n>>> name.last\n'Smith'\n>>> name = Namefully(['Edison', 'Thomas'], ordered_by='last_name')\n>>> name.first\n'Thomas'\n```\n\n> **Note**: The order of appearance set initially will be prioritized in other\n> operations. However, it can be adjusted dynamically as needed. See the example below.\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully('Smith John Joe', ordered_by='last_name')\n>>> name.full\n'Smith John Joe'\n>>> name.full_name(ordered_by='first_name')\n'John Joe Smith'\n```\n\n### separator\n\n`'' | , | : | \" | - | . | ; | ' | ' ' | _]` - default: `' '` (white space)\n\nSupported separators are: empty, comma, colon, double quotes, hyphen, period,\nsemicolon, single quote, white space, and underscore.\nThough _only valid for raw string values_, `separator` indicates how to split the\nparts of a raw string name under the hood. If you want more control, use a custom\n`Parser`.\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully('John,Smith', separator=',')\n>>> name.full\n'John Smith'\n```\n\n### title\n\n`uk | us` - default: `uk`\n\n`title` abides by the ways the international community defines an abbreviated title.\nAmerican and Canadian English follow slightly different rules for abbreviated\ntitles than British and Australian English. In North American English, titles\nbefore a name require a period: `Mr., Mrs., Ms., Dr.`. In British and Australian\nEnglish, no periods are used in these abbreviations.\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully.only(prefix='Mr', first='John', last='Smith', title='us')\n>>> name.full\n'Mr. John Smith'\n>>> name.prefix\n'Mr.'\n```\n\n### ending\n\n`bool` - default: `False`\n\nThis sets an ending character after the full name (a comma before the suffix actually).\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully.only('John', 'Smith', suffix='PhD', ending=True)\n>>> name.full\n'John Smith, PhD'\n>>> name.suffix\n'PhD'\n```\n\n### surname\n\n`father | mother | hyphenated | all` - default: `father`\n\n`surname` defines the distinct formats to output a compound surname (e.g., Hispanic surnames).\n\n```python\n>>> from namefully import Namefully, FirstName, LastName\n>>> name = Namefully([FirstName('John'), LastName('Doe', 'Smith')], surname='hyphenated')\n>>> name.full\n'John Doe-Smith'\n```\n\n### bypass\n\n`bool` - default: `True`\n\nThis will bypass all the built-in validators (i.e., validation rules, regular expressions).\n\n```python\n>>> from namefully import Namefully\n>>> name = Namefully.only('Jane', 'Smith', suffix='M.Sc', bypass=False)\nTraceback (most recent call last):\n ...\nValidationError (suffix='M.Sc'): invalid content\n```\n\nTo sum it all up, the default values are:\n\n```python\n>>> from namefully import Config\n>>> config = Config.create()\n>>> config\n<Config: default>\n>>> config.to_dict()\n{'name': 'default', 'ordered_by': 'first_name', 'separator': ' ', 'title': 'uk', 'ending': False, 'bypass': False, 'surname': 'father'}\n```\n\n## Do It Yourself\n\nCustomize your own parser to indicate the full name yourself.\n\n```python\nfrom namefully import Namefully, Parser, FullName\n\nclass SimpleParser(Parser):\n def parse(self, **options) -> FullName:\n fn, ln = self.raw.split('#')\n return FullName.parse({'first_name': fn, 'last_name': ln}, **options)\n\nname = Namefully(SimpleParser('Juan#Garcia'))\nprint(name.full) # Juan Garcia\n```\n\n## Concepts and examples\n\nThe name standards used for the current version of this library are as follows:\n\n`[prefix] first_name [middle_name] last_name [suffix]`\n\nThe opening `[` and closing `]` brackets mean that these parts are optional. In\nother words, the most basic/typical case is a name that looks like this:\n`John Smith`, where `John` is the _firstName_ and `Smith`, the _lastName_.\n\n> **NOTE**: Do note that the order of appearance matters and (as shown in [ordered_by](#ordered_by))\n> can be altered through configured parameters. By default, the order of appearance\n> is as shown above and will be used as a basis for future examples and use cases.\n\n### Basic cases\n\nLet us take a common example:\n\n`Mr John Joe Smith PhD`\n\nSo, this utility understands the name parts as follows:\n\n- prefix: `Mr`\n- first name: `John`\n- middle name: `Joe`\n- last name: `Smith`\n- suffix: `PhD`\n- full name: `Mr John Joe Smith PhD`\n- birth name: `John Joe Smith`\n- short version: `John Smith`\n- flattened: `John J. S.`\n- initials: `J J S`\n- public: `John S`\n- salutation: `Mr Smith`\n\n### Limitations\n\n`namefully` does not support certain use cases:\n\n- mononame: `Plato` - a workaround is to set the mononame as both first and last name;\n- multiple prefixes or suffixes: `Prof. Dr. Einstein`.\n\n## Contributing\n\nVisit [CONTRIBUTING.md][contributing-url] for details on the contribution guidelines,\nthe code of conduct, and the process for submitting pull requests.\n\n## License\n\nThe underlying content of this utility is licensed under [MIT][license-url].\n\n<!-- References -->\n\n[version-img]: https://img.shields.io/pypi/v/namefully\n[version-url]: https://pypi.python.org/pypi/namefully\n[license-img]: https://img.shields.io/pypi/l/namefully\n[license-url]: https://github.com/ralflorent/namefully-python/blob/main/LICENSE\n[downloads-img]: https://img.shields.io/pypi/dm/namefully\n[ci-img]: https://github.com/ralflorent/namefully-python/workflows/Build/badge.svg\n[ci-url]: https://github.com/ralflorent/namefully-python/actions/workflows/build.yml\n\n[contributing-url]: https://github.com/ralflorent/namefully-python/blob/main/CONTRIBUTING.md\n[examples]: https://github.com/ralflorent/namefully-python/blob/main/examples/main.py\n[test cases]:https://github.com/ralflorent/namefully-python/blob/main/test\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python utility for handling person names in a particular order, way, or shape.",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/ralflorent/namefully-python/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/ralflorent/namefully-python/blob/main/README.md",
"Repository": "https://github.com/ralflorent/namefully-python"
},
"split_keywords": [
"format",
" name"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bfe6fd95b7a23f3cb4f767c3841b638a0dac89c195849c1c3addb705fed55764",
"md5": "8a9d3b8ad7531f688eb3f43f0a26e28f",
"sha256": "624914ca08542bf04dc5feee6904c8cd72310fdc523e8e15f1a3ec47f4453e06"
},
"downloads": -1,
"filename": "namefully-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8a9d3b8ad7531f688eb3f43f0a26e28f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 20376,
"upload_time": "2024-11-24T05:34:06",
"upload_time_iso_8601": "2024-11-24T05:34:06.489719Z",
"url": "https://files.pythonhosted.org/packages/bf/e6/fd95b7a23f3cb4f767c3841b638a0dac89c195849c1c3addb705fed55764/namefully-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15e0b2faf5b73d924f59f50ef6274c88a04f32632c609c22bbf0461d08224180",
"md5": "d46b5818a708feaf2cc0f69336f3e940",
"sha256": "01d373a78fe3e63cf6a578a071f492a38a71a79ebe96a8ca2c08034f6ff7045d"
},
"downloads": -1,
"filename": "namefully-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d46b5818a708feaf2cc0f69336f3e940",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16554,
"upload_time": "2024-11-24T05:34:08",
"upload_time_iso_8601": "2024-11-24T05:34:08.045212Z",
"url": "https://files.pythonhosted.org/packages/15/e0/b2faf5b73d924f59f50ef6274c88a04f32632c609c22bbf0461d08224180/namefully-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 05:34:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ralflorent",
"github_project": "namefully-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "namefully"
}
