django-picklefield
==================
.. image:: https://img.shields.io/pypi/l/django-picklefield.svg?style=flat
:target: https://pypi.python.org/pypi/django-picklefield/
:alt: License
.. image:: https://img.shields.io/pypi/v/django-picklefield.svg?style=flat
:target: https://pypi.python.org/pypi/django-picklefield/
:alt: Latest Version
.. image:: https://github.com/gintas/django-picklefield/workflows/Test/badge.svg?branch=master
:target: https://github.com/gintas/django-picklefield/actions
:alt: Build Status
.. image:: https://coveralls.io/repos/gintas/django-picklefield/badge.svg?branch=master
:target: https://coveralls.io/r/gintas/django-picklefield?branch=master
:alt: Coverage Status
.. image:: https://img.shields.io/pypi/pyversions/django-picklefield.svg?style=flat
:target: https://pypi.python.org/pypi/django-picklefield/
:alt: Supported Python Versions
.. image:: https://img.shields.io/pypi/wheel/django-picklefield.svg?style=flat
:target: https://pypi.python.org/pypi/django-picklefield/
:alt: Wheel Status
-----
About
-----
**django-picklefield** provides an implementation of a pickled object field.
Such fields can contain any picklable objects.
The implementation is taken and adopted from `Django snippet #1694`_ by Taavi
Taijala, which is in turn based on `Django snippet #513`_ by Oliver Beattie.
django-picklefield is available under the MIT license.
.. _Django snippet #1694: http://www.djangosnippets.org/snippets/1694/
.. _Django snippet #513: http://www.djangosnippets.org/snippets/513/
-----
Usage
-----
First of all, you need to have **django-picklefield** installed; for your
convenience, recent versions should be available from PyPI.
To use, just define a field in your model:
.. code:: python
>>> from picklefield.fields import PickledObjectField
... class SomeObject(models.Model):
... args = PickledObjectField()
and assign whatever you like (as long as it's picklable) to the field:
.. code:: python
>>> obj = SomeObject()
>>> obj.args = ['fancy', {'objects': 'inside'}]
>>> obj.save()
-----
Notes
-----
If you need to serialize an object with a PickledObjectField for transmission
to the browser, you may need to subclass the field and override the
``value_to_string()`` method. Currently pickle fields are serialized as
base64-encoded pickles, which allows reliable deserialization, but such a
format is not convenient for parsing in the browser. By overriding
``value_to_string()`` you can choose a more convenient serialization format.
Fields now accept the boolean key word argument `copy`, which defaults to
`True`. The `copy` is necessary for lookups to work correctly. If you don't
care about performing lookups on the picklefield, you can set `copy=False` to
save on some memory usage. This an be especially beneficial for very large
object trees.
-------------
Running tests
-------------
The full test suite can be run with `Tox`_::
>>> pip install tox
>>> tox
.. _Tox: https://testrun.org/tox/latest/
--------------
Original notes
--------------
Here are the notes by taavi223, the original author:
Incredibly useful for storing just about anything in the database (provided it
is Pickle-able, of course) when there isn't a 'proper' field for the job.
PickledObjectField is database-agnostic, and should work with any database
backend you can throw at it. You can pass in any Python object and it will
automagically be converted behind the scenes. You never have to manually pickle
or unpickle anything. Also works fine when querying; supports exact, in, and
isnull lookups. It should be noted, however, that calling QuerySet.values()
will only return the encoded data, not the original Python object.
This PickledObjectField has a few improvements over the one in snippet #513.
This one solves the DjangoUnicodeDecodeError problem when saving an object
containing non-ASCII data by base64 encoding the pickled output stream. This
ensures that all stored data is ASCII, eliminating the problem.
PickledObjectField will now optionally use zlib to compress (and uncompress)
pickled objects on the fly. This can be set per-field using the keyword
argument "compress=True". For most items this is probably not worth the small
performance penalty, but for Models with larger objects, it can be a real space
saver.
You can also now specify the pickle protocol per-field, using the protocol
keyword argument. The default of 2 should always work, unless you are trying to
access the data from outside of the Django ORM.
Worked around a rare issue when using the cPickle and performing lookups of
complex data types. In short, cPickle would sometimes output different streams
for the same object depending on how it was referenced. This of course could
cause lookups for complex objects to fail, even when a matching object exists.
See the docstrings and tests for more information.
You can now use the isnull lookup and have it function as expected. A
consequence of this is that by default, PickledObjectField has null=True set
(you can of course pass null=False if you want to change that). If null=False
is set (the default for fields), then you wouldn't be able to store a Python
None value, since None values aren't pickled or encoded (this in turn is what
makes the isnull lookup possible).
You can now pass in an object as the default argument for the field without it
being converted to a unicode string first. If you pass in a callable though,
the field will still call it. It will not try to pickle and encode it.
You can manually import dbsafe_encode and dbsafe_decode from fields.py if you
want to encode and decode objects yourself. This is mostly useful for decoding
values returned from calling QuerySet.values(), which are still encoded
strings.
Note: If you are trying to store other django models in the PickledObjectField,
please see the comments for a discussion on the problems associated with doing
that. The easy solution is to put django models into a list or tuple before
assigning them to the PickledObjectField.
Update 9/2/09: Fixed the value_to_string method so that serialization should
now work as expected. Also added deepcopy back into dbsafe_encode, fixing #4
above, since deepcopy had somehow managed to remove itself. This means that
lookups should once again work as expected in all situations. Also made the
field editable=False by default (which I swear I already did once before!)
since it is never a good idea to have a PickledObjectField be user editable.
-------
Changes
-------
Changes in version 3.2.0
========================
* Added tested support for Django 4.1, 4.2, 5.0.
* Added tested support for Python 3.11, 3.12.
* Dropped support for Python 3.6 and 3.7.
Changes in version 3.1.0
========================
* Added tested support for Django 3.2 and 4.0.
Changes in version 3.0.1
========================
* None; addressed a packaging issue with 3.0.0
Changes in version 3.0.0
========================
* Allowed default pickle protocol to be overriden using the
`PICKLEFIELD_DEFAULT_PROTOCOL` setting.
* Dropped support for Python 2.
* Added testing against Django 3.0.
* Dropped support for Django 1.11.
Changes in version 2.1.0
========================
* Added official support for Django 2.2 (thanks to joehybird).
* Dropped support for Django 2.0 and 2.1 (thanks to joehybird).
* Dropped support for Python 3.4 (thanks to joehybidd).
Changes in version 2.0.0
========================
* Silenced ``RemovedInDjango30Warning`` warnings on Django 2.0+ (thanks to
canarduck).
* Restructured project directories.
* Disallowed the usage of empty strings for ``PickledObjectField``. That makes
``.save()``, ``.create()``, etc. raise ``IntegrityError`` if `null` is not
``True`` and no default value was specified like built-in fields do
(thanks to Attila-Mihaly Balazs).
* Added a check for mutable default values to ``PickledObjectField``.
Changes in version 1.1.0
========================
* Added support for Django 2.1 and dropped support for Django < 1.11.
Changes in version 1.0.0
========================
* Added a new option to prevent a copy of the object before pickling: `copy=True`
* Dropped support for Django 1.4
* Dropped support for Django 1.7
* Dropped support for Python 3.2
* Added support for Python 3.6
Changes in version 0.3.2
========================
* Dropped support for Django 1.3.
* Dropped support for Python 2.5.
* Silenced deprecation warnings on Django 1.8+.
Changes in version 0.3.1
========================
* Favor the built in json module (thanks to Simon Charette).
Changes in version 0.3.0
========================
* Python 3 support (thanks to Rafal Stozek).
Changes in version 0.2.0
========================
* Allow pickling of subclasses of django.db.models.Model (thanks to Simon
Charette).
Changes in version 0.1.9
========================
* Added `connection` and `prepared` parameters to `get_db_prep_value()` too
(thanks to Matthew Schinckel).
Changes in version 0.1.8
========================
* Updated link to code repository.
Changes in version 0.1.7
========================
* Added `connection` and `prepared` parameters to `get_db_prep_lookup()` to
get rid of deprecation warnings in Django 1.2.
Changes in version 0.1.6
========================
* Fixed South support (thanks aehlke@github).
Changes in version 0.1.5
========================
* Added support for South.
* Changed default to null=False, as is common throughout Django.
Changes in version 0.1.4
========================
* Updated copyright statements.
Changes in version 0.1.3
========================
* Updated serialization tests (thanks to Michael Fladischer).
Changes in version 0.1.2
========================
* Added Simplified BSD licence.
Changes in version 0.1.1
========================
* Added test for serialization.
* Added note about JSON serialization for browser.
* Added support for different pickle protocol versions (thanks to Michael
Fladischer).
Changes in version 0.1
======================
* First public release.
--------
Feedback
--------
There is a home page <http://github.com/gintas/django-picklefield>
with instructions on how to access the code repository.
Send feedback and suggestions to gintautas@miliauskas.lt .
Raw data
{
"_id": null,
"home_page": "http://github.com/gintas/django-picklefield",
"name": "django-picklefield",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "django pickle model field",
"author": "Simon Charette",
"author_email": "charette.s+django-picklefiel@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9f/37/449e9425a33eed4dfe39baf43cc2643f3d5ecd47dca4545d705b3f5ccc1a/django-picklefield-3.2.tar.gz",
"platform": null,
"description": "django-picklefield\n==================\n\n.. image:: https://img.shields.io/pypi/l/django-picklefield.svg?style=flat\n :target: https://pypi.python.org/pypi/django-picklefield/\n :alt: License\n\n.. image:: https://img.shields.io/pypi/v/django-picklefield.svg?style=flat\n :target: https://pypi.python.org/pypi/django-picklefield/\n :alt: Latest Version\n\n.. image:: https://github.com/gintas/django-picklefield/workflows/Test/badge.svg?branch=master\n :target: https://github.com/gintas/django-picklefield/actions\n :alt: Build Status\n\n.. image:: https://coveralls.io/repos/gintas/django-picklefield/badge.svg?branch=master\n :target: https://coveralls.io/r/gintas/django-picklefield?branch=master\n :alt: Coverage Status\n\n.. image:: https://img.shields.io/pypi/pyversions/django-picklefield.svg?style=flat\n :target: https://pypi.python.org/pypi/django-picklefield/\n :alt: Supported Python Versions\n\n.. image:: https://img.shields.io/pypi/wheel/django-picklefield.svg?style=flat\n :target: https://pypi.python.org/pypi/django-picklefield/\n :alt: Wheel Status\n\n-----\nAbout\n-----\n\n**django-picklefield** provides an implementation of a pickled object field.\nSuch fields can contain any picklable objects.\n\nThe implementation is taken and adopted from `Django snippet #1694`_ by Taavi\nTaijala, which is in turn based on `Django snippet #513`_ by Oliver Beattie.\n\ndjango-picklefield is available under the MIT license.\n\n.. _Django snippet #1694: http://www.djangosnippets.org/snippets/1694/\n.. _Django snippet #513: http://www.djangosnippets.org/snippets/513/\n\n-----\nUsage\n-----\n\nFirst of all, you need to have **django-picklefield** installed; for your\nconvenience, recent versions should be available from PyPI.\n\nTo use, just define a field in your model:\n\n.. code:: python\n\n >>> from picklefield.fields import PickledObjectField\n ... class SomeObject(models.Model):\n ... args = PickledObjectField()\n\nand assign whatever you like (as long as it's picklable) to the field:\n\n.. code:: python\n\n >>> obj = SomeObject()\n >>> obj.args = ['fancy', {'objects': 'inside'}]\n >>> obj.save()\n\n\n-----\nNotes\n-----\n\nIf you need to serialize an object with a PickledObjectField for transmission\nto the browser, you may need to subclass the field and override the\n``value_to_string()`` method. Currently pickle fields are serialized as\nbase64-encoded pickles, which allows reliable deserialization, but such a\nformat is not convenient for parsing in the browser. By overriding\n``value_to_string()`` you can choose a more convenient serialization format.\n\nFields now accept the boolean key word argument `copy`, which defaults to\n`True`. The `copy` is necessary for lookups to work correctly. If you don't\ncare about performing lookups on the picklefield, you can set `copy=False` to\nsave on some memory usage. This an be especially beneficial for very large\nobject trees.\n\n-------------\nRunning tests\n-------------\n\nThe full test suite can be run with `Tox`_::\n\n >>> pip install tox\n >>> tox\n\n.. _Tox: https://testrun.org/tox/latest/\n\n--------------\nOriginal notes\n--------------\n\nHere are the notes by taavi223, the original author:\n\nIncredibly useful for storing just about anything in the database (provided it\nis Pickle-able, of course) when there isn't a 'proper' field for the job.\n\nPickledObjectField is database-agnostic, and should work with any database\nbackend you can throw at it. You can pass in any Python object and it will\nautomagically be converted behind the scenes. You never have to manually pickle\nor unpickle anything. Also works fine when querying; supports exact, in, and\nisnull lookups. It should be noted, however, that calling QuerySet.values()\nwill only return the encoded data, not the original Python object.\n\nThis PickledObjectField has a few improvements over the one in snippet #513.\n\nThis one solves the DjangoUnicodeDecodeError problem when saving an object\ncontaining non-ASCII data by base64 encoding the pickled output stream. This\nensures that all stored data is ASCII, eliminating the problem.\n\nPickledObjectField will now optionally use zlib to compress (and uncompress)\npickled objects on the fly. This can be set per-field using the keyword\nargument \"compress=True\". For most items this is probably not worth the small\nperformance penalty, but for Models with larger objects, it can be a real space\nsaver.\n\nYou can also now specify the pickle protocol per-field, using the protocol\nkeyword argument. The default of 2 should always work, unless you are trying to\naccess the data from outside of the Django ORM.\n\nWorked around a rare issue when using the cPickle and performing lookups of\ncomplex data types. In short, cPickle would sometimes output different streams\nfor the same object depending on how it was referenced. This of course could\ncause lookups for complex objects to fail, even when a matching object exists.\nSee the docstrings and tests for more information.\n\nYou can now use the isnull lookup and have it function as expected. A\nconsequence of this is that by default, PickledObjectField has null=True set\n(you can of course pass null=False if you want to change that). If null=False\nis set (the default for fields), then you wouldn't be able to store a Python\nNone value, since None values aren't pickled or encoded (this in turn is what\nmakes the isnull lookup possible).\n\nYou can now pass in an object as the default argument for the field without it\nbeing converted to a unicode string first. If you pass in a callable though,\nthe field will still call it. It will not try to pickle and encode it.\n\nYou can manually import dbsafe_encode and dbsafe_decode from fields.py if you\nwant to encode and decode objects yourself. This is mostly useful for decoding\nvalues returned from calling QuerySet.values(), which are still encoded\nstrings.\n\nNote: If you are trying to store other django models in the PickledObjectField,\nplease see the comments for a discussion on the problems associated with doing\nthat. The easy solution is to put django models into a list or tuple before\nassigning them to the PickledObjectField.\n\nUpdate 9/2/09: Fixed the value_to_string method so that serialization should\nnow work as expected. Also added deepcopy back into dbsafe_encode, fixing #4\nabove, since deepcopy had somehow managed to remove itself. This means that\nlookups should once again work as expected in all situations. Also made the\nfield editable=False by default (which I swear I already did once before!)\nsince it is never a good idea to have a PickledObjectField be user editable.\n\n-------\nChanges\n-------\n\nChanges in version 3.2.0\n========================\n\n* Added tested support for Django 4.1, 4.2, 5.0.\n* Added tested support for Python 3.11, 3.12.\n* Dropped support for Python 3.6 and 3.7.\n\nChanges in version 3.1.0\n========================\n\n* Added tested support for Django 3.2 and 4.0.\n\nChanges in version 3.0.1\n========================\n\n* None; addressed a packaging issue with 3.0.0\n\nChanges in version 3.0.0\n========================\n\n* Allowed default pickle protocol to be overriden using the\n `PICKLEFIELD_DEFAULT_PROTOCOL` setting.\n* Dropped support for Python 2.\n* Added testing against Django 3.0.\n* Dropped support for Django 1.11.\n\nChanges in version 2.1.0\n========================\n\n* Added official support for Django 2.2 (thanks to joehybird).\n* Dropped support for Django 2.0 and 2.1 (thanks to joehybird).\n* Dropped support for Python 3.4 (thanks to joehybidd).\n\nChanges in version 2.0.0\n========================\n\n* Silenced ``RemovedInDjango30Warning`` warnings on Django 2.0+ (thanks to\n canarduck).\n* Restructured project directories.\n* Disallowed the usage of empty strings for ``PickledObjectField``. That makes\n ``.save()``, ``.create()``, etc. raise ``IntegrityError`` if `null` is not\n ``True`` and no default value was specified like built-in fields do\n (thanks to Attila-Mihaly Balazs).\n* Added a check for mutable default values to ``PickledObjectField``.\n\nChanges in version 1.1.0\n========================\n\n* Added support for Django 2.1 and dropped support for Django < 1.11.\n\nChanges in version 1.0.0\n========================\n\n* Added a new option to prevent a copy of the object before pickling: `copy=True`\n* Dropped support for Django 1.4\n* Dropped support for Django 1.7\n* Dropped support for Python 3.2\n* Added support for Python 3.6\n\nChanges in version 0.3.2\n========================\n\n* Dropped support for Django 1.3.\n* Dropped support for Python 2.5.\n* Silenced deprecation warnings on Django 1.8+.\n\nChanges in version 0.3.1\n========================\n\n* Favor the built in json module (thanks to Simon Charette).\n\nChanges in version 0.3.0\n========================\n\n* Python 3 support (thanks to Rafal Stozek).\n\nChanges in version 0.2.0\n========================\n\n* Allow pickling of subclasses of django.db.models.Model (thanks to Simon\n Charette).\n\nChanges in version 0.1.9\n========================\n\n* Added `connection` and `prepared` parameters to `get_db_prep_value()` too\n (thanks to Matthew Schinckel).\n\nChanges in version 0.1.8\n========================\n\n* Updated link to code repository.\n\nChanges in version 0.1.7\n========================\n\n* Added `connection` and `prepared` parameters to `get_db_prep_lookup()` to\n get rid of deprecation warnings in Django 1.2.\n\nChanges in version 0.1.6\n========================\n\n* Fixed South support (thanks aehlke@github).\n\nChanges in version 0.1.5\n========================\n\n* Added support for South.\n* Changed default to null=False, as is common throughout Django.\n\nChanges in version 0.1.4\n========================\n\n* Updated copyright statements.\n\nChanges in version 0.1.3\n========================\n\n* Updated serialization tests (thanks to Michael Fladischer).\n\nChanges in version 0.1.2\n========================\n\n* Added Simplified BSD licence.\n\nChanges in version 0.1.1\n========================\n\n* Added test for serialization.\n* Added note about JSON serialization for browser.\n* Added support for different pickle protocol versions (thanks to Michael\n Fladischer).\n\nChanges in version 0.1\n======================\n\n* First public release.\n\n\n--------\nFeedback\n--------\n\nThere is a home page <http://github.com/gintas/django-picklefield>\nwith instructions on how to access the code repository.\n\nSend feedback and suggestions to gintautas@miliauskas.lt .\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pickled object field for Django",
"version": "3.2",
"project_urls": {
"Homepage": "http://github.com/gintas/django-picklefield"
},
"split_keywords": [
"django",
"pickle",
"model",
"field"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "52f91502538efa2d4cd3a88ff806cdbd08b1c681dd828d05b6dbc8bcb50a8586",
"md5": "e684b04eb4fbda9ad42fa6c41fa5cc4d",
"sha256": "e9a73539d110f69825d9320db18bcb82e5189ff48dbed41821c026a20497764c"
},
"downloads": -1,
"filename": "django_picklefield-3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e684b04eb4fbda9ad42fa6c41fa5cc4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 9533,
"upload_time": "2024-04-05T02:23:01",
"upload_time_iso_8601": "2024-04-05T02:23:01.860879Z",
"url": "https://files.pythonhosted.org/packages/52/f9/1502538efa2d4cd3a88ff806cdbd08b1c681dd828d05b6dbc8bcb50a8586/django_picklefield-3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f37449e9425a33eed4dfe39baf43cc2643f3d5ecd47dca4545d705b3f5ccc1a",
"md5": "c82e35a250e5135ce0603d0090a11d4e",
"sha256": "aa463f5d79d497dbe789f14b45180f00a51d0d670067d0729f352a3941cdfa4d"
},
"downloads": -1,
"filename": "django-picklefield-3.2.tar.gz",
"has_sig": false,
"md5_digest": "c82e35a250e5135ce0603d0090a11d4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 9520,
"upload_time": "2024-04-05T02:23:03",
"upload_time_iso_8601": "2024-04-05T02:23:03.965916Z",
"url": "https://files.pythonhosted.org/packages/9f/37/449e9425a33eed4dfe39baf43cc2643f3d5ecd47dca4545d705b3f5ccc1a/django-picklefield-3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-05 02:23:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gintas",
"github_project": "django-picklefield",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-picklefield"
}
JSON
