# gelidum
[](https://opensource.org/licenses/MIT)
[](https://github.com/diegojromerolopez/gelidum/graphs/commit-activity)
[](https://www.python.org/)
[](https://pypi.python.org/pypi/gelidum/)
[](https://pypi.python.org/pypi/gelidum/)
[](https://pypi.python.org/pypi/gelidum/)
[](https://pypi.python.org/pypi/gelidum/)
[](https://codeclimate.com/github/diegojromerolopez/gelidum/maintainability)
[](https://codeclimate.com/github/diegojromerolopez/gelidum/test_coverage)
Freeze your objects in python.
[Public domain photo](https://www.flickr.com/photos/140296773@N07/45771062385) by [Katsujiro Maekawa](https://www.flickr.com/photos/hjppo/)
| Latin | English |
| -------------------------------------------------------- | -------------------------------------------------------- |
| *Caelum est hieme frigidum et gelidum; myrtos oleas quaeque alia assiduo tepore laetantur, aspernatur ac respuit; laurum tamen patitur atque etiam nitidissimam profert, interdum sed non saepius quam sub urbe nostra necat.* | *In winter the air is cold and frosty: myrtles, olives and all other trees which require constant warmth for them to do well, the climate rejects and spurns, though it allows laurel to grow, and even brings it to a luxuriant leaf. Occasionally, however, it kills it, but that does not happen more frequently than in the neighbourhood of Rome.* |
[The Letters of the Younger Pliny, First Series — Volume 1 by the Younger Pliny](https://www.gutenberg.org/ebooks/3234), translated to English by John Benjamin Firth.
## Introduction
Inspired by the method freeze found in other languages like Javascript,
this package tries to make immutable objects to make it easier avoiding
accidental modifications in your code.
See more comments about this project in this [Show HN](https://news.ycombinator.com/item?id=27507524).
## Major highlights
- **freeze** method creates objects with the same attributes of inputs that cannot be expanded or modified.
- Frozen object creation is thread-safe.
- Structural sharing: any frozen object is shared by all of its user objects. There is no copy
performed, only reference.
- cpython and pypy support.
## How it works
In case of the [builtin types](https://docs.python.org/3/library/stdtypes.html)
(bool, None, int, float, bytes, complex, str) it does nothing, as they are already immutable.
For the list type, a [frozenlist](/gelidum/collections/frozenlist.py) with frozen items is returned.
Tuples are already immutable, so a new tuple with frozen items is returned.
When freezing a set, a [frozenzet](/gelidum/collections/frozenzet.py) of frozen items is returned.
In the case of dicts, freezing one of them creates
a new [frozendict](/gelidum/collections/frozendict.py)
with the keys and frozen values of the original dict.
This package, change the methods \_\_setattr\_\_, \_\_delattr\_\_, \_\_set\_\_,
\_\_setitem\_\_, and \_\_delitem\_\_ of the object argument and all of its attributed recursively,
making them raise an exception if the developer tries to call them to modify
the attributes of the instance.
## How to use it
### Freeze in the same object
```python
from typing import List
from gelidum import freeze
class Dummy(object):
def __init__(self, attr1: int, attr2: List):
self.attr1 = attr1
self.attr2 = attr2
dummy = Dummy(1, [2, 3, 4])
frozen_dummy = freeze(dummy, on_freeze="inplace")
assert(id(dummy) == id(frozen_dummy))
# Both raise exception
new_value = 1
dummy.attr1 = new_value
frozen_dummy.attr1 = new_value
# Both raise exception
new_value_list = [1]
dummy.attr2 = new_value_list
frozen_dummy.attr2 = new_value_list
```
### Freeze in a new object
#### Basic use
```python
from typing import List
from gelidum import freeze
class Dummy(object):
def __init__(self, attr1: int, attr2: List):
self.attr1 = attr1
self.attr2 = attr2
dummy = Dummy(1, [2, 3, 4])
# on_freeze="copy" by default
frozen_dummy = freeze(dummy)
assert(id(dummy) != id(frozen_dummy))
# on_freeze="copy" by default
frozen_object_dummy2 = freeze(dummy, on_freeze="copy")
# It doesn't raise an exception,
# dummy keeps being a mutable object
new_attr1_value = 99
dummy.attr1 = new_attr1_value
# Raises exception,
# frozen_dummy is an immutable object
frozen_dummy.attr1 = new_attr1_value
```
#### Access to original object
##### Passing flag to freezer
If you are freezing custom objects, you can pass the flag `save_original_on_copy` to the freeze method to
ensure you have an attribute original_obj in the frozen method.
```python
from gelidum import freeze
class Dummy(object):
def __init__(self, attr1: int, attr2: int):
self.attr1 = attr1
self.attr2 = attr2
dummy = Dummy(1, 2)
frozen_dummy = freeze(dummy, save_original_on_copy=True)
# We are copying the object and freezing it:
assert(id(dummy) != id(frozen_dummy))
# But we are keeping the original object inside it:
assert(id(dummy) == id(frozen_dummy.original_obj))
```
##### Custom freezer
The parameter on_freeze admits a callable, so you can have
some side effects when freezing objects.
There is a particular callable class that allows
returning the original object:
```python
from gelidum import freeze
from gelidum.on_freeze import OnFreezeOriginalObjTracker
class Dummy(object):
def __init__(self, value1: int, value2: int):
self.attr1 = value1
self.attr2 = value2
dummy = Dummy(value1=1, value2=2)
freezer = OnFreezeOriginalObjTracker()
frozen_dummy = freeze(dummy, on_freeze=freezer)
original_obj = freezer.original_obj
assert(dummy == original_obj)
```
Note that in the earlier case the original object is not frozen
but a copy of it.
#### What to do when trying to update an attribute
```python
import logging
from gelidum import freeze
class SharedState(object):
def __init__(self, count: int):
self.count = count
shared_state = SharedState(1)
# on_update="exception": raises an exception when an update is tried
frozen_shared_state = freeze(shared_state, on_update="exception")
frozen_shared_state.count = 4 # Raises exception
# on_update="warning": shows a warning in console exception when an update is tried
frozen_shared_state = freeze(shared_state, on_update="warning")
frozen_shared_state.count = 4 # Shows a warning in console
# on_update="nothing": does nothing when an update is tried
frozen_shared_state = freeze(shared_state, on_update="nothing")
frozen_shared_state.count = 4 # Does nothing, as this update did not exist
# on_update=<lambda message, *args, **kwargs>: calls the function
# Note the parameters of that function must be message, *args, **kwargs
frozen_shared_state = freeze(
shared_state,
on_update=lambda message, *args, **kwargs: logging.warning(message)
)
frozen_shared_state.count = 4 # Calls on_update function and logs in the warning level:
# "Can't assign 'count' on immutable instance"
```
### Freeze input params
Use the decorator freeze_params to freeze the input parameters
and avoid non-intended modifications:
```python
from typing import List
from gelidum import freeze_params
@freeze_params()
def append_to_list(a_list: List, new_item: int):
a_list.append(new_item)
```
If freeze_params is called without arguments, all input parameters will be frozen.
Otherwise, passing a set of parameters will inform the decorator of which named
parameters must be frozen.
```python
from typing import List
from gelidum import freeze_params
@freeze_params(params={"list1", "list2"})
def concat_lists(dest: List, list1: List, list2: List) -> List:
dest = list1 + list2
return dest
# Freeze dest, list1 and list2
concat_lists([], list1=[1, 2, 3], list2=[4, 5, 6])
# Freeze list1 and list2
concat_lists(dest=[], list1=[1, 2, 3], list2=[4, 5, 6])
```
Always use kwargs unless you want to freeze the args params. A good way to enforce this is by making the
function have keyword-only arguments:
```python
from typing import List
from gelidum import freeze_params
@freeze_params(params={"list1", "list2"})
def concat_lists_in(*, dest: List, list1: List, list2: List):
dest = list1 + list2
return dest
```
You can use the **Final typehint from gelidum** to signal that an argument is immutable:
```python
from typing import List
from gelidum import freeze_final, Final
@freeze_final
def concatenate_lists(list1: Final[List], list2: Final[List]):
return list1 + list2
```
Finally, take in account that all freezing is done in a new object (i.e. freeze with on_freeze="copy").
It makes no sense to freeze a parameter of a function that could be used later, *outside*
said function.
### Check original (i.e. "hot") class
- **get_gelidum_hot_class_name**: returns the name of hot class.
- **get_gelidum_hot_class_module** returns the module reference where the hot class was.
## Collections
There are four immutable collections in the gelidum.collections module.
- frozendict
- frozenlist
- frozenzet (frozenset is already a builtin type in Python)
All of these classes can be used to make sure a collection of objects
is not modified. Indeed, when creating a new collection object, you
can pass a custom freeze function, to customize the freezing process
of each of its items, e.g.:
```python
import logging
from gelidum.freeze import freeze
from gelidum.collections import frozenzet
from gelidum.typing import FrozenType
from typing import Any
def my_freeze_func(item: Any) -> FrozenType:
logging.debug(f"Freezing item {item}")
return freeze(item, on_update="exception", on_freeze="copy")
frozen_zet = frozenzet([1, 2, 3], freeze_func=my_freeze_func)
```
## Rationale and background information
Inspired by my old work with Ruby on Rails, I decided to create a mechanism to make
objects immutable in Python. The first aim was to do a tool to avoid accidental
modifications on the objects while passing them through an execution flow.
Anyways, as time passed I thought that an implementation of a programming language
with real threading support (i.e. not cpython) could be benefited from this feature.
I know that both cpython and pypy implementations of the Python programming
language have a [GIL](https://en.wikipedia.org/wiki/Global_interpreter_lock) but IronPython
and [Graalpython](https://github.com/oracle/graalpython) don't.
IronPython3 has no support for typehintings yet,
but Graalpython seems to work fine, so more experiments will be coming.
On the other hand, I'm also interested in creating functional data structures
in this package, easing the life of developers that do not want side effects.
It's true that the complexity of Python does not play well with this kind of library.
Thus, Python usually serves as easy interface with native libraries (pandas, numpy, etc.)
However, this project is fun to develop and maybe with the popularity of alternative
implementations of Python some work can be done to improve performance.
More information can be seen in this [Show HN post](https://news.ycombinator.com/item?id=27507524)
and some appreciated feedback of the users of that great community.
## Limitations
- dict, list, tuple and set objects cannot be modified inplace although the flag inplace is set.
- file handler attributes are not supported. An exception is raised when trying to freeze
an object with them.
- frozen objects cannot be serialized with [marshal](https://docs.python.org/3/library/marshal.html).
- frozen objects cannot be (deep)-copied. This limitation is intended to make structural sharing easier.
- Classes with \_\_slots\_\_:
- cannot be frozen in-place.
- will be frozen with a unique class. The frozen class will not be shared by instances of the same class.
## Advice & comments on use
### On_update parameter of freeze function
Use on_update with a callable to store when somebody tried to write in the immutable object:
```python
import datetime
import logging
import threading
from gelidum import freeze
class Dummy(object):
def __init__(self, attr: int):
self.attr = attr
class FrozenDummyUpdateTryRecorder:
LOCK = threading.Lock()
written_tries = []
@classmethod
def add_writing_try(cls, message, *args, **kwargs):
logging.warning(message)
with cls.LOCK:
cls.written_tries.append({
"message": message,
"args": args,
"kwargs": kwargs,
"datetime": datetime.datetime.utcnow()
})
dummy = Dummy(1)
frozen_dummy = freeze(
dummy,
on_update=FrozenDummyUpdateTryRecorder.add_writing_try
)
# It will call FrozenDummyUpdateTryRecorder.add_writing_try
# and will continue the execution flow with the next sentence.
frozen_dummy.attr = 4
```
### On_freeze parameter of freeze function
The parameter on_freeze of the function freeze must be a string or a callable.
This parameter informs of what to do with the object that will be frozen.
Should it be the same input object frozen or a copy of it?
If it has a string as parameter, values "inplace" and "copy" are allowed.
A value of "inplace" will make the freeze method to try to freeze the object
as-is, while a value of "copy" will make a copy of the original object and then,
freeze that copy. **These are the recommended parameters**.
On the other hand, the interesting part is to define a custom on_freeze method.
This method must return an object of the same type of the input.
**This returned will be frozen, and returned to the caller of freeze**.
Note this parameter has no interference with the structural sharing of the frozen objects.
Any frozen object that have several references to it will be shared, not copied.
```python
import copy
def on_freeze(self, obj: object) -> object:
frozen_object = copy.deepcopy(obj)
# log, copy the original method or do any other
# custom action in this function
return frozen_object
```
As seen earlier, there is also the possibility to
pass a callable object. If you would like you can even
define your own on_freeze functions by inheriting
from classes:
- OnFreezeCopier
- OnFreezeIdentityFunc
See some examples in [on_freeze.py](/gelidum/on_freeze.py) file.
## Dependencies
This package has no dependencies.
## Roadmap
- [x] Freeze only when attributes are modified?
Not exactly but structural sharing is used.
- [x] Include immutable collections.
- [ ] [Graalpython](https://github.com/oracle/graalpython) support.
- [ ] Make some use-cases with threading/async module (i.e. server)
## Collaborations
This project is open to collaborations. Make a PR or an issue,
and I'll take a look to it.
## License
[MIT](LICENSE) license, but if you need any other contact me.
Raw data
{
"_id": null,
"home_page": "https://github.com/diegojromerolopez/gelidum",
"name": "gelidum",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "freeze python object",
"author": "Diego J. Romero L\u00f3pez",
"author_email": "diegojromerolopez@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/12/ff/87ef210dd10ef1e25e2214ece9f6a19b1f07db9209e8ca32ffede0d6877e/gelidum-0.7.0.tar.gz",
"platform": null,
"description": "# gelidum\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/diegojromerolopez/gelidum/graphs/commit-activity)\n[](https://www.python.org/)\n[](https://pypi.python.org/pypi/gelidum/)\n[](https://pypi.python.org/pypi/gelidum/)\n[](https://pypi.python.org/pypi/gelidum/)\n[](https://pypi.python.org/pypi/gelidum/)\n[](https://codeclimate.com/github/diegojromerolopez/gelidum/maintainability)\n[](https://codeclimate.com/github/diegojromerolopez/gelidum/test_coverage)\n\nFreeze your objects in python.\n\n![Gelidum](https://raw.githubusercontent.com/diegojromerolopez/gelidum/main/resources/gelidum.jpg \"Gelidum image\")\n\n[Public domain photo](https://www.flickr.com/photos/140296773@N07/45771062385) by [Katsujiro Maekawa](https://www.flickr.com/photos/hjppo/)\n\n| Latin | English |\n| -------------------------------------------------------- | -------------------------------------------------------- |\n| *Caelum est hieme frigidum et gelidum; myrtos oleas quaeque alia assiduo tepore laetantur, aspernatur ac respuit; laurum tamen patitur atque etiam nitidissimam profert, interdum sed non saepius quam sub urbe nostra necat.* | *In winter the air is cold and frosty: myrtles, olives and all other trees which require constant warmth for them to do well, the climate rejects and spurns, though it allows laurel to grow, and even brings it to a luxuriant leaf. Occasionally, however, it kills it, but that does not happen more frequently than in the neighbourhood of Rome.* |\n\n[The Letters of the Younger Pliny, First Series \u2014 Volume 1 by the Younger Pliny](https://www.gutenberg.org/ebooks/3234), translated to English by John Benjamin Firth.\n\n## Introduction\nInspired by the method freeze found in other languages like Javascript,\nthis package tries to make immutable objects to make it easier avoiding\naccidental modifications in your code.\n\nSee more comments about this project in this [Show HN](https://news.ycombinator.com/item?id=27507524).\n\n## Major highlights\n- **freeze** method creates objects with the same attributes of inputs that cannot be expanded or modified.\n- Frozen object creation is thread-safe.\n- Structural sharing: any frozen object is shared by all of its user objects. There is no copy\nperformed, only reference.\n- cpython and pypy support.\n\n## How it works\nIn case of the [builtin types](https://docs.python.org/3/library/stdtypes.html)\n(bool, None, int, float, bytes, complex, str) it does nothing, as they are already immutable.\n\nFor the list type, a [frozenlist](/gelidum/collections/frozenlist.py) with frozen items is returned.\n\nTuples are already immutable, so a new tuple with frozen items is returned.\n\nWhen freezing a set, a [frozenzet](/gelidum/collections/frozenzet.py) of frozen items is returned.\n\nIn the case of dicts, freezing one of them creates\na new [frozendict](/gelidum/collections/frozendict.py)\nwith the keys and frozen values of the original dict.\n\nThis package, change the methods \\_\\_setattr\\_\\_, \\_\\_delattr\\_\\_, \\_\\_set\\_\\_,\n\\_\\_setitem\\_\\_, and \\_\\_delitem\\_\\_ of the object argument and all of its attributed recursively,\nmaking them raise an exception if the developer tries to call them to modify\nthe attributes of the instance.\n\n## How to use it\n\n### Freeze in the same object\n```python\nfrom typing import List\nfrom gelidum import freeze\n\nclass Dummy(object):\n def __init__(self, attr1: int, attr2: List):\n self.attr1 = attr1\n self.attr2 = attr2\n\ndummy = Dummy(1, [2, 3, 4])\nfrozen_dummy = freeze(dummy, on_freeze=\"inplace\")\nassert(id(dummy) == id(frozen_dummy))\n\n# Both raise exception\nnew_value = 1\ndummy.attr1 = new_value\nfrozen_dummy.attr1 = new_value\n\n# Both raise exception\nnew_value_list = [1]\ndummy.attr2 = new_value_list\nfrozen_dummy.attr2 = new_value_list\n```\n\n### Freeze in a new object\n\n#### Basic use\n```python\nfrom typing import List\nfrom gelidum import freeze\n\nclass Dummy(object):\n def __init__(self, attr1: int, attr2: List):\n self.attr1 = attr1\n self.attr2 = attr2\n\ndummy = Dummy(1, [2, 3, 4])\n# on_freeze=\"copy\" by default\nfrozen_dummy = freeze(dummy)\nassert(id(dummy) != id(frozen_dummy))\n\n# on_freeze=\"copy\" by default\nfrozen_object_dummy2 = freeze(dummy, on_freeze=\"copy\")\n\n# It doesn't raise an exception,\n# dummy keeps being a mutable object\nnew_attr1_value = 99\ndummy.attr1 = new_attr1_value\n\n# Raises exception,\n# frozen_dummy is an immutable object\nfrozen_dummy.attr1 = new_attr1_value\n```\n\n#### Access to original object\n##### Passing flag to freezer\nIf you are freezing custom objects, you can pass the flag `save_original_on_copy` to the freeze method to\nensure you have an attribute original_obj in the frozen method.\n\n```python\nfrom gelidum import freeze\n\nclass Dummy(object):\n def __init__(self, attr1: int, attr2: int):\n self.attr1 = attr1\n self.attr2 = attr2\n\ndummy = Dummy(1, 2)\nfrozen_dummy = freeze(dummy, save_original_on_copy=True)\n\n# We are copying the object and freezing it:\nassert(id(dummy) != id(frozen_dummy))\n# But we are keeping the original object inside it:\nassert(id(dummy) == id(frozen_dummy.original_obj))\n```\n\n##### Custom freezer\nThe parameter on_freeze admits a callable, so you can have\nsome side effects when freezing objects.\n\nThere is a particular callable class that allows\nreturning the original object:\n\n```python\nfrom gelidum import freeze\nfrom gelidum.on_freeze import OnFreezeOriginalObjTracker\n\nclass Dummy(object):\n def __init__(self, value1: int, value2: int):\n self.attr1 = value1\n self.attr2 = value2\n\ndummy = Dummy(value1=1, value2=2)\n\nfreezer = OnFreezeOriginalObjTracker()\n\nfrozen_dummy = freeze(dummy, on_freeze=freezer)\noriginal_obj = freezer.original_obj\n\nassert(dummy == original_obj)\n```\n\nNote that in the earlier case the original object is not frozen\nbut a copy of it.\n\n#### What to do when trying to update an attribute\n```python\nimport logging\nfrom gelidum import freeze\n\nclass SharedState(object):\n def __init__(self, count: int):\n self.count = count\n\nshared_state = SharedState(1)\n \n# on_update=\"exception\": raises an exception when an update is tried\nfrozen_shared_state = freeze(shared_state, on_update=\"exception\")\nfrozen_shared_state.count = 4 # Raises exception\n\n# on_update=\"warning\": shows a warning in console exception when an update is tried\nfrozen_shared_state = freeze(shared_state, on_update=\"warning\")\nfrozen_shared_state.count = 4 # Shows a warning in console\n\n# on_update=\"nothing\": does nothing when an update is tried\nfrozen_shared_state = freeze(shared_state, on_update=\"nothing\")\nfrozen_shared_state.count = 4 # Does nothing, as this update did not exist\n\n# on_update=<lambda message, *args, **kwargs>: calls the function\n# Note the parameters of that function must be message, *args, **kwargs\nfrozen_shared_state = freeze(\n shared_state,\n on_update=lambda message, *args, **kwargs: logging.warning(message)\n)\nfrozen_shared_state.count = 4 # Calls on_update function and logs in the warning level:\n # \"Can't assign 'count' on immutable instance\" \n```\n\n\n### Freeze input params\nUse the decorator freeze_params to freeze the input parameters\nand avoid non-intended modifications:\n```python\nfrom typing import List\nfrom gelidum import freeze_params\n\n@freeze_params()\ndef append_to_list(a_list: List, new_item: int):\n a_list.append(new_item)\n```\nIf freeze_params is called without arguments, all input parameters will be frozen.\nOtherwise, passing a set of parameters will inform the decorator of which named\nparameters must be frozen.\n\n```python\nfrom typing import List\nfrom gelidum import freeze_params\n\n@freeze_params(params={\"list1\", \"list2\"})\ndef concat_lists(dest: List, list1: List, list2: List) -> List:\n dest = list1 + list2\n return dest\n\n# Freeze dest, list1 and list2\nconcat_lists([], list1=[1, 2, 3], list2=[4, 5, 6])\n\n# Freeze list1 and list2\nconcat_lists(dest=[], list1=[1, 2, 3], list2=[4, 5, 6])\n```\n\nAlways use kwargs unless you want to freeze the args params. A good way to enforce this is by making the\nfunction have keyword-only arguments:\n\n```python\nfrom typing import List\nfrom gelidum import freeze_params\n\n@freeze_params(params={\"list1\", \"list2\"})\ndef concat_lists_in(*, dest: List, list1: List, list2: List):\n dest = list1 + list2\n return dest\n```\n\nYou can use the **Final typehint from gelidum** to signal that an argument is immutable:\n\n```python\nfrom typing import List\nfrom gelidum import freeze_final, Final\n\n@freeze_final\ndef concatenate_lists(list1: Final[List], list2: Final[List]):\n return list1 + list2\n```\n\nFinally, take in account that all freezing is done in a new object (i.e. freeze with on_freeze=\"copy\").\nIt makes no sense to freeze a parameter of a function that could be used later, *outside*\nsaid function.\n\n### Check original (i.e. \"hot\") class\n- **get_gelidum_hot_class_name**: returns the name of hot class.\n- **get_gelidum_hot_class_module** returns the module reference where the hot class was.\n\n## Collections\nThere are four immutable collections in the gelidum.collections module.\n\n- frozendict\n- frozenlist\n- frozenzet (frozenset is already a builtin type in Python)\n\nAll of these classes can be used to make sure a collection of objects\nis not modified. Indeed, when creating a new collection object, you\ncan pass a custom freeze function, to customize the freezing process\nof each of its items, e.g.:\n\n```python\nimport logging\nfrom gelidum.freeze import freeze\nfrom gelidum.collections import frozenzet\nfrom gelidum.typing import FrozenType\nfrom typing import Any\n\n\ndef my_freeze_func(item: Any) -> FrozenType:\n logging.debug(f\"Freezing item {item}\")\n return freeze(item, on_update=\"exception\", on_freeze=\"copy\")\n\nfrozen_zet = frozenzet([1, 2, 3], freeze_func=my_freeze_func)\n```\n\n## Rationale and background information\nInspired by my old work with Ruby on Rails, I decided to create a mechanism to make\nobjects immutable in Python. The first aim was to do a tool to avoid accidental\nmodifications on the objects while passing them through an execution flow.\n\nAnyways, as time passed I thought that an implementation of a programming language\nwith real threading support (i.e. not cpython) could be benefited from this feature.\nI know that both cpython and pypy implementations of the Python programming\nlanguage have a [GIL](https://en.wikipedia.org/wiki/Global_interpreter_lock) but IronPython\nand [Graalpython](https://github.com/oracle/graalpython) don't.\nIronPython3 has no support for typehintings yet,\nbut Graalpython seems to work fine, so more experiments will be coming.\n\nOn the other hand, I'm also interested in creating functional data structures\nin this package, easing the life of developers that do not want side effects.\n\nIt's true that the complexity of Python does not play well with this kind of library.\nThus, Python usually serves as easy interface with native libraries (pandas, numpy, etc.)\nHowever, this project is fun to develop and maybe with the popularity of alternative\nimplementations of Python some work can be done to improve performance.\n\nMore information can be seen in this [Show HN post](https://news.ycombinator.com/item?id=27507524)\nand some appreciated feedback of the users of that great community.\n\n## Limitations\n- dict, list, tuple and set objects cannot be modified inplace although the flag inplace is set.\n- file handler attributes are not supported. An exception is raised when trying to freeze\n an object with them.\n- frozen objects cannot be serialized with [marshal](https://docs.python.org/3/library/marshal.html).\n- frozen objects cannot be (deep)-copied. This limitation is intended to make structural sharing easier.\n- Classes with \\_\\_slots\\_\\_:\n - cannot be frozen in-place.\n - will be frozen with a unique class. The frozen class will not be shared by instances of the same class.\n\n## Advice & comments on use\n### On_update parameter of freeze function\nUse on_update with a callable to store when somebody tried to write in the immutable object:\n```python\nimport datetime\nimport logging\nimport threading\nfrom gelidum import freeze\n\n\nclass Dummy(object):\n def __init__(self, attr: int):\n self.attr = attr\n\n\nclass FrozenDummyUpdateTryRecorder:\n LOCK = threading.Lock()\n written_tries = []\n \n @classmethod\n def add_writing_try(cls, message, *args, **kwargs):\n logging.warning(message)\n with cls.LOCK:\n cls.written_tries.append({\n \"message\": message,\n \"args\": args,\n \"kwargs\": kwargs,\n \"datetime\": datetime.datetime.utcnow()\n })\n\n\ndummy = Dummy(1)\nfrozen_dummy = freeze(\n dummy,\n on_update=FrozenDummyUpdateTryRecorder.add_writing_try \n )\n# It will call FrozenDummyUpdateTryRecorder.add_writing_try\n# and will continue the execution flow with the next sentence.\nfrozen_dummy.attr = 4\n```\n\n### On_freeze parameter of freeze function\nThe parameter on_freeze of the function freeze must be a string or a callable.\nThis parameter informs of what to do with the object that will be frozen.\nShould it be the same input object frozen or a copy of it?\n\nIf it has a string as parameter, values \"inplace\" and \"copy\" are allowed.\nA value of \"inplace\" will make the freeze method to try to freeze the object\nas-is, while a value of \"copy\" will make a copy of the original object and then,\nfreeze that copy. **These are the recommended parameters**.\n\nOn the other hand, the interesting part is to define a custom on_freeze method.\nThis method must return an object of the same type of the input.\n**This returned will be frozen, and returned to the caller of freeze**.\n\nNote this parameter has no interference with the structural sharing of the frozen objects.\nAny frozen object that have several references to it will be shared, not copied.\n\n```python\nimport copy\n\ndef on_freeze(self, obj: object) -> object:\n frozen_object = copy.deepcopy(obj)\n # log, copy the original method or do any other\n # custom action in this function\n return frozen_object\n```\nAs seen earlier, there is also the possibility to\npass a callable object. If you would like you can even\ndefine your own on_freeze functions by inheriting\nfrom classes:\n\n- OnFreezeCopier\n- OnFreezeIdentityFunc\n\nSee some examples in [on_freeze.py](/gelidum/on_freeze.py) file.\n\n## Dependencies\nThis package has no dependencies.\n\n\n## Roadmap\n- [x] Freeze only when attributes are modified? \n Not exactly but structural sharing is used.\n- [x] Include immutable collections.\n- [ ] [Graalpython](https://github.com/oracle/graalpython) support.\n- [ ] Make some use-cases with threading/async module (i.e. server)\n\n\n## Collaborations\nThis project is open to collaborations. Make a PR or an issue,\nand I'll take a look to it.\n\n## License\n[MIT](LICENSE) license, but if you need any other contact me.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Freeze your python objects",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/diegojromerolopez/gelidum"
},
"split_keywords": [
"freeze",
"python",
"object"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12ff87ef210dd10ef1e25e2214ece9f6a19b1f07db9209e8ca32ffede0d6877e",
"md5": "2d1a9a83e56cab54e2a014ad51f65607",
"sha256": "726029916cca89cc0e5b4eec388ae3df15468a8fa8e96f996963520bec593709"
},
"downloads": -1,
"filename": "gelidum-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "2d1a9a83e56cab54e2a014ad51f65607",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32208,
"upload_time": "2023-10-08T17:48:38",
"upload_time_iso_8601": "2023-10-08T17:48:38.416949Z",
"url": "https://files.pythonhosted.org/packages/12/ff/87ef210dd10ef1e25e2214ece9f6a19b1f07db9209e8ca32ffede0d6877e/gelidum-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-08 17:48:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "diegojromerolopez",
"github_project": "gelidum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gelidum"
}
JSON
