| Name | bitint JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | |
| Summary | Pure Python implementation of extended integer with named bits. |
| upload_time | 2023-09-15 12:06:38 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023 Robin Gottfried 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. |
| keywords |
bit
int
set
flags
namedtuple
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# bit-int
Pure Python implementation of extended integer with named bits.
I found that some Python engineers find working with bit math as sets
unnatural. So I created this simple `int` extension to make bit manipulation
more Pythonic and to demonstrate the beauty of Python magic.
What is BitInt good for in real life? It's as efficient as Python's own `set`
type but it can be easily stored in databases, JSON or shared with other
languages without any modification (C, Go, Java, JavaScript).
BitInt is highly inspired by great
[namedtuple](https://docs.python.org/3/library/collections.html#collections.namedtuple)
from python standard library.
## Installation
pip install bit-int
or pipenv
pipenv install -e 'git+https://github.com/czervenka/bit-set.git#egg=bitint'
## Usage
>>> from bitint import bitint
BitInt is an integer type where bits can be named and manipulated as a set.
Let's create a class Animals with first 8 bits named after animals kinds:
>>> Animals = bitint('Animals', 'cat, dog, mouse, bee, turtle, snake, frog, axolotl')
In this case, animals are represented by bits where cat is the first bit
(2^0=1), dog is the second (2^1=2), mouse the third (2^2=4). You don't need to
remember which animal is represented by which bit, because each species bit value
is stored in property named after the species label:
>>> Animals.cat
1
Similarly `dog` label represents the second bit, which has value `2**1 = 2`
>>> Animals.dog
2
We can now instantiate a subset of animals with set bits which corresponds to amphibians...
>>> amphibians = Animals('frog', 'axolotl')
... or animals which are commonly pets...
>>> pets = Animals('cat', 'dog')
Bit representation of `pets` is
0 0 0 0 0 0 1 1
^ ^
| L cat (2^0 == 1 == Animals.cat)
L dog (2^1 == 2 == Animals.dog)
Having this two sets of animals, we can use bit magic to test whether an animal
bit is set to 1 or 0:
>>> "Dog is a pet" if Animals.dog & pets else "Dog is not a pet"
'Dog is a pet'
... or use `in` operator:
>>> Animals.dog in pets
True
What about if we try to check existence of an animal which has not been defined
yet?
>>> Animals.elefant in pets
Traceback (most recent call last):
...
AttributeError: type object 'Animals' has no attribute 'elefant'
Beside checking for existense, it's possible to make basic set operations. For
example, we can create a new Animals bitint which includes all pets and
amphibians:
>>> pets | amphibians
Animals('cat', 'dog', 'frog', 'axolotl')
We can also find an intersection:
>>> hairy_animals = Animals('cat', 'dog', 'mouse')
>>> hairy_animals & pets
Animals('cat', 'dog')
... and even complement
>>> ~pets
Animals('mouse', 'bee', 'turtle', 'snake', 'frog', 'axolotl')
A set of all animals can be created using bit inversion of no animal
>>> all_animals = ~Animals()
>>> all_animals
Animals('cat', 'dog', 'mouse', 'bee', 'turtle', 'snake', 'frog', 'axolotl')
Animals can be added or removed from all animals by `set` and `unset`
>>> all_animals.unset(Animals.dog, Animals.bee, Animals.snake)
Animals('cat', 'mouse', 'turtle', 'frog', 'axolotl')
If you are curious which bits are set for named flags, print a bitint value.
>>> print(amphibians)
11000000
>>> print(pets | amphibians)
11000011
Furthermore you can also create list of or iterate over names of set bits
>>> list(pets)
['cat', 'dog']
>>> for pet in pets:
... print(pet)
cat
dog
or for instance create regular Python set
>>> set(pets) == {'cat', 'dog'}
True
Beside everything else BitInt is just an enhanced integer :)
>>> pets + 1
4
>>> import json
>>> json.dumps({"pets_bitint": pets})
'{"pets_bitint": 3}'
**Tip:** If you change the named bits of a BitInt class (e.g. replace 'dog'
with 'elephant') and you have stored bitints you need to make a migration
otherwise all dogs become elephants. If you want to avoid migrations, never
change existing named bit and only add new at the end of definition to utilize
unused bits.
**Update:** My daughter found a bug in this readme:
>>> pets |= Animals.axolotl
>>> list(pets)
['cat', 'dog', 'axolotl']
## Testing
Tests are documentation and vice-versa:
python -m doctest bitint.py README.md
Raw data
{
"_id": null,
"home_page": "",
"name": "bitint",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "bit,int,set,flags,namedtuple",
"author": "",
"author_email": "Robin Gottfried <bitint@kebet.cz>",
"download_url": "https://files.pythonhosted.org/packages/74/71/d52dc45bace50815d15bcb939c344515ad1c545ce65e8999c11f72387655/bitint-0.1.4.tar.gz",
"platform": null,
"description": "# bit-int\n\nPure Python implementation of extended integer with named bits.\n\nI found that some Python engineers find working with bit math as sets\nunnatural. So I created this simple `int` extension to make bit manipulation\nmore Pythonic and to demonstrate the beauty of Python magic.\n\nWhat is BitInt good for in real life? It's as efficient as Python's own `set`\ntype but it can be easily stored in databases, JSON or shared with other\nlanguages without any modification (C, Go, Java, JavaScript).\n\nBitInt is highly inspired by great\n[namedtuple](https://docs.python.org/3/library/collections.html#collections.namedtuple)\nfrom python standard library.\n\n## Installation\n\n pip install bit-int\n\nor pipenv\n\n pipenv install -e 'git+https://github.com/czervenka/bit-set.git#egg=bitint'\n\n## Usage\n\n >>> from bitint import bitint\n\nBitInt is an integer type where bits can be named and manipulated as a set.\nLet's create a class Animals with first 8 bits named after animals kinds:\n\n >>> Animals = bitint('Animals', 'cat, dog, mouse, bee, turtle, snake, frog, axolotl')\n\nIn this case, animals are represented by bits where cat is the first bit\n(2^0=1), dog is the second (2^1=2), mouse the third (2^2=4). You don't need to\nremember which animal is represented by which bit, because each species bit value\nis stored in property named after the species label:\n\n >>> Animals.cat\n 1\n\nSimilarly `dog` label represents the second bit, which has value `2**1 = 2`\n\n >>> Animals.dog\n 2\n\nWe can now instantiate a subset of animals with set bits which corresponds to amphibians...\n\n >>> amphibians = Animals('frog', 'axolotl')\n\n... or animals which are commonly pets...\n\n >>> pets = Animals('cat', 'dog')\n\nBit representation of `pets` is\n\n 0 0 0 0 0 0 1 1\n ^ ^\n | L cat (2^0 == 1 == Animals.cat)\n L dog (2^1 == 2 == Animals.dog)\n\nHaving this two sets of animals, we can use bit magic to test whether an animal\nbit is set to 1 or 0:\n\n >>> \"Dog is a pet\" if Animals.dog & pets else \"Dog is not a pet\"\n 'Dog is a pet'\n\n... or use `in` operator:\n\n >>> Animals.dog in pets\n True\n\nWhat about if we try to check existence of an animal which has not been defined\nyet?\n\n >>> Animals.elefant in pets\n Traceback (most recent call last):\n ...\n AttributeError: type object 'Animals' has no attribute 'elefant'\n\nBeside checking for existense, it's possible to make basic set operations. For\nexample, we can create a new Animals bitint which includes all pets and\namphibians:\n\n >>> pets | amphibians\n Animals('cat', 'dog', 'frog', 'axolotl')\n\nWe can also find an intersection:\n\n >>> hairy_animals = Animals('cat', 'dog', 'mouse')\n >>> hairy_animals & pets\n Animals('cat', 'dog')\n\n... and even complement\n\n >>> ~pets\n Animals('mouse', 'bee', 'turtle', 'snake', 'frog', 'axolotl')\n\nA set of all animals can be created using bit inversion of no animal\n\n >>> all_animals = ~Animals()\n >>> all_animals\n Animals('cat', 'dog', 'mouse', 'bee', 'turtle', 'snake', 'frog', 'axolotl')\n\nAnimals can be added or removed from all animals by `set` and `unset`\n\n >>> all_animals.unset(Animals.dog, Animals.bee, Animals.snake)\n Animals('cat', 'mouse', 'turtle', 'frog', 'axolotl')\n\n\nIf you are curious which bits are set for named flags, print a bitint value.\n\n >>> print(amphibians)\n 11000000\n >>> print(pets | amphibians)\n 11000011\n\nFurthermore you can also create list of or iterate over names of set bits\n\n >>> list(pets)\n ['cat', 'dog']\n >>> for pet in pets:\n ... print(pet)\n cat\n dog\n\nor for instance create regular Python set\n\n >>> set(pets) == {'cat', 'dog'}\n True\n\nBeside everything else BitInt is just an enhanced integer :)\n\n >>> pets + 1\n 4\n >>> import json\n >>> json.dumps({\"pets_bitint\": pets})\n '{\"pets_bitint\": 3}'\n\n\n**Tip:** If you change the named bits of a BitInt class (e.g. replace 'dog'\nwith 'elephant') and you have stored bitints you need to make a migration\notherwise all dogs become elephants. If you want to avoid migrations, never\nchange existing named bit and only add new at the end of definition to utilize\nunused bits.\n\n\n\n**Update:** My daughter found a bug in this readme:\n\n >>> pets |= Animals.axolotl\n >>> list(pets)\n ['cat', 'dog', 'axolotl']\n\n## Testing\n\nTests are documentation and vice-versa:\n\n python -m doctest bitint.py README.md\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Robin Gottfried 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. ",
"summary": "Pure Python implementation of extended integer with named bits.",
"version": "0.1.4",
"project_urls": {
"homepage": "https://github.com/czervenka/bit-int",
"repository": "https://github.com/czervenka/bit-int.git"
},
"split_keywords": [
"bit",
"int",
"set",
"flags",
"namedtuple"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7157616d2827ade1c47b7732dcfa1ed9595b85cab8877adc21e85e4f5aaf4181",
"md5": "7630f2318af241a94b722631e68a4d2f",
"sha256": "cb35e766f0af13b5b5c0b6e3999e033f3ad50cf1b6cefd977c3a20c585469b88"
},
"downloads": -1,
"filename": "bitint-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7630f2318af241a94b722631e68a4d2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6033,
"upload_time": "2023-09-15T12:06:37",
"upload_time_iso_8601": "2023-09-15T12:06:37.130046Z",
"url": "https://files.pythonhosted.org/packages/71/57/616d2827ade1c47b7732dcfa1ed9595b85cab8877adc21e85e4f5aaf4181/bitint-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7471d52dc45bace50815d15bcb939c344515ad1c545ce65e8999c11f72387655",
"md5": "d47f0ffcdf4753f456dfc9fe33c00a1f",
"sha256": "f10bb72c4372e6b9b275f3b2b5ffc919137c63703e575c69fc80910b6f787c4d"
},
"downloads": -1,
"filename": "bitint-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "d47f0ffcdf4753f456dfc9fe33c00a1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5303,
"upload_time": "2023-09-15T12:06:38",
"upload_time_iso_8601": "2023-09-15T12:06:38.877126Z",
"url": "https://files.pythonhosted.org/packages/74/71/d52dc45bace50815d15bcb939c344515ad1c545ce65e8999c11f72387655/bitint-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-15 12:06:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "czervenka",
"github_project": "bit-int",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bitint"
}
