# Strings by Ouroboros Coding
[](https://pypi.org/project/Strings-OC) 
Generic functions for dealing with and generating strings
## Requires
Strings-OC requires python 3.10 or higher
## Installation
```bash
pip install Strings-OC
```
## Functions
### bytes_human
Returns a human readable string using the number passed as a representation of bytes
```python
>>> from strings import bytes_human
>>> bytes_human(1024)
'1.0KiB'
>>> bytes_human(1024*1024)
'1.0MiB'
>>> bytes_human(1024*1024*1024+1000000000)
'1.9GiB'
```
### digits
Returns only the digits, i.e. the numeric characters, in the given string as a new string. Be careful, as this does not return numbers, but number characters, and will strip out valid float/decimal characters
```python
>>> from strings import digits
>>> digits('1234abcd')
'1234'
>>> digits('a1b2c3d4')
'1234'
>>> digits('3.1415')
'31415'
>>> digits('1e+7')
'17'
```
### from_file
Returns the entire file as a string
```python
>>> from strings import from_file
>>> from_file('version.dat')
'1.0.1\n'
```
Assuming `version.dat` contained the following
```
1.0.1
```
If the file doesn't exist, `from_file` returns `None`. This can be changed by passing a second argument to be the default value.
```python
>>> from strings import from_file
>>> from_file('doesnotexist', '1.0.0')
'1.0.0'
```
### normalize
Returns, as well as possible, a normalized string converted from another string containing characters with special accents. It does this by finding special characters and converting them into their simpler, single character, versions. This is useful for things like automaticlaly generating urls, or for generating from unicode into ascii.
```python
>>> from strings import normalize
>>> normalize('Ȟěƚľỡ, Ẉợɽḷᶁ!')
'Hello, World!'
>>> normalize('ffiDzǼij')
'ffiDAEij'
```
### random
Returns a random string based on set parameters.
```python
>>> from strings import random
>>> random()
'NQFsxVTi'
>>> random()
'KFCMjKQg'
>>> random()
'HJEvCjlA'
```
`random` can takes 3 optional parameters.
#### length
`length` represents the number of random characters you wish to return.
```python
>>> random(length = 10)
'PvIwnubCyN'
>>> random(length = 4)
'bGXE'
>>> random(16)
'WMLdawtSCEFeNtsg'
```
#### characters
`characters` represents the set of chars that are allowed in the string. There is no limit on this list, and no necessity the values be different. This allows for modifying the randomness if there are characters you want to make "more random"
```python
>>> random(8, 'AAAAa')
'AAAAAAAA'
>>> random(length = 8, characters = 'AAAaa')
'aAAAAAaA'
>>> random(characters = 'AAaaa', length = 8)
'aaaaAAaA'
```
`characters` can be set using special built in sets, and can be accessed by passing a list instead of a string
```python
>>> random(16, ['aZ'])
'KwDNSoFPlVVTxwhj'
>>> random(characters = ['az*', '10'])
'a003jsut'
>>> random(characters = ['0x'], length = 32)
'9ce511ab223cef1d65c400ce2e836759'
```
| name | characters |
| --- | --- |
| 0x | 0123456789abcdef |
| 0 | 01234567 |
| 10 | 0123456789 |
| az | abcdefghijklmnopqrstuvwxyz |
| az* | abcdefghijkmnopqrstuvwxyz |
| AZ | ABCDEFGHIJKLMNOPQRSTUVWXYZ |
| AZ* | ABCDEFGHJKLMNPQRSTUVWXYZ |
| aZ | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ |
| aZ* | abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ |
| ! | !@#$%^&*-_+.? |
| !* | !@$%^*-_. |
\* sets denote removal of characters that might confuse, either systems or humans. &, #, etc for the former, and I, l, O, etc for the latter.
#### duplicates
By default `random` allows duplicate characters in a string, and doesn't see any issue with that. But it's possible you have an issue with it, and want a string made up completely of non-repeating characters. If so, set `duplicates` to `False`.
```python
>>> random(16, ['az'], False)
'ifaunxgtzbywkmpr'
>>> random(26, ['az'], False)
'rmqghwsayntkpizfbeldvcxoju'
>>> random(27, ['az'], False)
ValueError: Can not generate random string with no duplicates from the given characters "abcdefghijklmnopqrstuvwxyz" in random
```
### strtr
`strtr` is a partial copy of the [PHP functon](https://www.php.net/manual/en/function.strtr.php) of the same name. This version does not support the singular use of one $from, and one $to, but the same can be achieved by using a dict with a single key and value. The primary purpose of this function is to be the actual workhorse of the `normalize` function, but there's no reason other people can't make use of it.
```python
>>> from strings import strtr
>>> strtr('Hello, World!', {'World': 'Chris'})
'Hello, Chris!'
```
### to_bool
`to_bool` is useful for turning any string into a valid boolean. But will raise an exception if the value does not represent a bool as it sees it. First, it converts the string to lowercase, then it checks it against the following:
Valid `True` values contain '1', 'on', 't', 'true', 'y', 'yes', 'x'
Valid `False` values contain '0', 'f', 'false', 'n', 'no', 'off', ''
```python
>>> from strings import to_bool
>>> to_bool('true')
True
>>> to_bool('F')
False
>>> to_bool('2')
ValueError: "2" is not a valid boolean representation in to_bool
```
### to_file
Stores a string in a file, overwriting the existing contents, or creating the file if it didn't exist.
```python
>>> from strings import to_file
>>> to_file('version.dat', '1.1.0')
True
```
The `version.dat` file will now contain the following
```
1.1.0
```
### uuid_add_dashes
Used to add dashes "-" to a string representation of a UUID that has none.
```python
>>> from strings import uuid_add_dashes
>>> uuid_add_dashes('b22eb45ac98311eca05a80fa5b0d7c77')
'b22eb45a-c983-11ec-a05a-80fa5b0d7c77'
```
### uuid_strip_dashes
Used to strip dashes "-" from a string representation of a UUID that has them.
```python
>>> from strings import uuid_strip_dashes
>>> uuid_strip_dashes('b22eb45a-c983-11ec-a05a-80fa5b0d7c77')
'b22eb45ac98311eca05a80fa5b0d7c77'
```
### version_compare
Compares to version strings and returns if the first is less than (-1), equal to (0) or greater than (1) the second
```python
>>> from strings import version_compare
>>> version_compare('1.0.1', '1.0')
1
>>> version_compare('1.0.1', '1.0.1')
0
>>> version_compare('1.0.1', '1.1')
-1
```
Raw data
{
"_id": null,
"home_page": "https://ouroboroscoding.com/strings/",
"name": "Strings-OC",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "strings,string manipulation,string generation",
"author": "Chris Nasr - Ouroboros Coding Inc.",
"author_email": "chris@ouroboroscoding.com",
"download_url": "https://files.pythonhosted.org/packages/2f/d7/25c8075722de0ad69716ce266978f430a501535e7a1213f06b13800ea401/Strings-OC-1.0.1.tar.gz",
"platform": null,
"description": "# Strings by Ouroboros Coding\n[](https://pypi.org/project/Strings-OC) \n\nGeneric functions for dealing with and generating strings\n\n## Requires\nStrings-OC requires python 3.10 or higher\n\n## Installation\n```bash\npip install Strings-OC\n```\n\n## Functions\n\n### bytes_human\nReturns a human readable string using the number passed as a representation of bytes\n```python\n>>> from strings import bytes_human\n>>>\tbytes_human(1024)\n'1.0KiB'\n>>> bytes_human(1024*1024)\n'1.0MiB'\n>>> bytes_human(1024*1024*1024+1000000000)\n'1.9GiB'\n```\n\n### digits\nReturns only the digits, i.e. the numeric characters, in the given string as a new string. Be careful, as this does not return numbers, but number characters, and will strip out valid float/decimal characters\n```python\n>>> from strings import digits\n>>> digits('1234abcd')\n'1234'\n>>> digits('a1b2c3d4')\n'1234'\n>>> digits('3.1415')\n'31415'\n>>> digits('1e+7')\n'17'\n```\n\n### from_file\nReturns the entire file as a string\n\n```python\n>>> from strings import from_file\n>>> from_file('version.dat')\n'1.0.1\\n'\n```\n\nAssuming `version.dat` contained the following\n\n```\n1.0.1\n\n```\n\nIf the file doesn't exist, `from_file` returns `None`. This can be changed by passing a second argument to be the default value.\n\n```python\n>>> from strings import from_file\n>>> from_file('doesnotexist', '1.0.0')\n'1.0.0'\n```\n\n### normalize\nReturns, as well as possible, a normalized string converted from another string containing characters with special accents. It does this by finding special characters and converting them into their simpler, single character, versions. This is useful for things like automaticlaly generating urls, or for generating from unicode into ascii.\n```python\n>>> from strings import normalize\n>>> normalize('\u021e\u011b\u019a\u013e\u1ee1, \u1e88\u1ee3\u027d\u1e37\u1d81!')\n'Hello, World!'\n>>> normalize('\ufb03\u01f2\u01fc\u0133')\n'ffiDAEij'\n```\n\n### random\nReturns a random string based on set parameters.\n```python\n>>> from strings import random\n>>> random()\n'NQFsxVTi'\n>>> random()\n'KFCMjKQg'\n>>> random()\n'HJEvCjlA'\n```\n`random` can takes 3 optional parameters.\n#### length\n`length` represents the number of random characters you wish to return.\n```python\n>>> random(length = 10)\n'PvIwnubCyN'\n>>> random(length = 4)\n'bGXE'\n>>> random(16)\n'WMLdawtSCEFeNtsg'\n```\n#### characters\n`characters` represents the set of chars that are allowed in the string. There is no limit on this list, and no necessity the values be different. This allows for modifying the randomness if there are characters you want to make \"more random\"\n```python\n>>> random(8, 'AAAAa')\n'AAAAAAAA'\n>>> random(length = 8, characters = 'AAAaa')\n'aAAAAAaA'\n>>> random(characters = 'AAaaa', length = 8)\n'aaaaAAaA'\n```\n`characters` can be set using special built in sets, and can be accessed by passing a list instead of a string\n```python\n>>> random(16, ['aZ'])\n'KwDNSoFPlVVTxwhj'\n>>> random(characters = ['az*', '10'])\n'a003jsut'\n>>> random(characters = ['0x'], length = 32)\n'9ce511ab223cef1d65c400ce2e836759'\n```\n\n| name | characters |\n| --- | --- |\n| 0x | 0123456789abcdef |\n| 0 | 01234567 |\n| 10 | 0123456789 |\n| az | abcdefghijklmnopqrstuvwxyz |\n| az* | abcdefghijkmnopqrstuvwxyz |\n| AZ | ABCDEFGHIJKLMNOPQRSTUVWXYZ |\n| AZ* | ABCDEFGHJKLMNPQRSTUVWXYZ |\n| aZ | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ |\n| aZ* | abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ |\n| ! | !@#$%^&*-_+.? |\n| !* | !@$%^*-_. |\n\n\\* sets denote removal of characters that might confuse, either systems or humans. &, #, etc for the former, and I, l, O, etc for the latter.\n#### duplicates\nBy default `random` allows duplicate characters in a string, and doesn't see any issue with that. But it's possible you have an issue with it, and want a string made up completely of non-repeating characters. If so, set `duplicates` to `False`.\n```python\n>>> random(16, ['az'], False)\n'ifaunxgtzbywkmpr'\n>>> random(26, ['az'], False)\n'rmqghwsayntkpizfbeldvcxoju'\n>>> random(27, ['az'], False)\nValueError: Can not generate random string with no duplicates from the given characters \"abcdefghijklmnopqrstuvwxyz\" in random\n```\n### strtr\n`strtr` is a partial copy of the [PHP functon](https://www.php.net/manual/en/function.strtr.php) of the same name. This version does not support the singular use of one $from, and one $to, but the same can be achieved by using a dict with a single key and value. The primary purpose of this function is to be the actual workhorse of the `normalize` function, but there's no reason other people can't make use of it.\n```python\n>>> from strings import strtr\n>>> strtr('Hello, World!', {'World': 'Chris'})\n'Hello, Chris!'\n```\n\n### to_bool\n`to_bool` is useful for turning any string into a valid boolean. But will raise an exception if the value does not represent a bool as it sees it. First, it converts the string to lowercase, then it checks it against the following:\nValid `True` values contain '1', 'on', 't', 'true', 'y', 'yes', 'x'\nValid `False` values contain '0', 'f', 'false', 'n', 'no', 'off', ''\n```python\n>>> from strings import to_bool\n>>> to_bool('true')\nTrue\n>>> to_bool('F')\nFalse\n>>> to_bool('2')\nValueError: \"2\" is not a valid boolean representation in to_bool\n```\n\n### to_file\nStores a string in a file, overwriting the existing contents, or creating the file if it didn't exist.\n```python\n>>> from strings import to_file\n>>> to_file('version.dat', '1.1.0')\nTrue\n```\nThe `version.dat` file will now contain the following\n```\n1.1.0\n```\n\n### uuid_add_dashes\nUsed to add dashes \"-\" to a string representation of a UUID that has none.\n```python\n>>> from strings import uuid_add_dashes\n>>> uuid_add_dashes('b22eb45ac98311eca05a80fa5b0d7c77')\n'b22eb45a-c983-11ec-a05a-80fa5b0d7c77'\n```\n\n### uuid_strip_dashes\nUsed to strip dashes \"-\" from a string representation of a UUID that has them.\n```python\n>>> from strings import uuid_strip_dashes\n>>> uuid_strip_dashes('b22eb45a-c983-11ec-a05a-80fa5b0d7c77')\n'b22eb45ac98311eca05a80fa5b0d7c77'\n```\n\n### version_compare\nCompares to version strings and returns if the first is less than (-1), equal to (0) or greater than (1) the second\n```python\n>>> from strings import version_compare\n>>> version_compare('1.0.1', '1.0')\n1\n>>> version_compare('1.0.1', '1.0.1')\n0\n>>> version_compare('1.0.1', '1.1')\n-1\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generic functions for dealing with and generating strings",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://ouroboroscoding.com/strings/",
"Homepage": "https://ouroboroscoding.com/strings/",
"Source": "https://github.com/ouroboroscoding/strings-python",
"Tracker": "https://github.com/ouroboroscoding/strings-python/issues"
},
"split_keywords": [
"strings",
"string manipulation",
"string generation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2fd725c8075722de0ad69716ce266978f430a501535e7a1213f06b13800ea401",
"md5": "29d7d576ab98208cf70f284d4943991b",
"sha256": "51ddcc691a3085eaceec29768a1fd33e6d364c22ae3b7a406f942a62ae6f3762"
},
"downloads": -1,
"filename": "Strings-OC-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "29d7d576ab98208cf70f284d4943991b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11484,
"upload_time": "2023-07-16T11:52:52",
"upload_time_iso_8601": "2023-07-16T11:52:52.854007Z",
"url": "https://files.pythonhosted.org/packages/2f/d7/25c8075722de0ad69716ce266978f430a501535e7a1213f06b13800ea401/Strings-OC-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-16 11:52:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ouroboroscoding",
"github_project": "strings-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "strings-oc"
}
JSON
