django-salesforce
=================
.. image:: https://github.com/django-salesforce/django-salesforce/actions/workflows/main.yml/badge.svg
:target: https://github.com/django-salesforce/django-salesforce/actions/workflows/main.yml
.. image:: https://badge.fury.io/py/django-salesforce.svg
:target: https://pypi.python.org/pypi/django-salesforce
.. image:: https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg
:target: https://www.python.org/
.. image:: https://img.shields.io/badge/Django-2.1%2C%202.2%20%7C%203.0%2C%203.1%20%2C%203.2%20%7C%204.0%2C%204.1%2C%204.2%20%7C%205.0-blue.svg
:target: https://www.djangoproject.com/
This library allows you to load, edit and query the objects in any Salesforce instance
using Django models. The integration is fairly complete, and generally seamless
for most uses. It works by integrating with the Django ORM, allowing access to
the objects in your SFDC instance (Salesforce .com) as if they were in a
traditional database.
Python 3.8 to 3.12, Django 2.1 to 5.0. (Tested also with Python 3.13b1)
Use with Django 5.0 or 4.2(LTS) currently requires an enteprise license key DJSF_LICENSE_KEY
until August 2024 unless you accept the AGPL license and install our otherwise identical
package "django-salesforce-agpl" instead. The license keys are available to sponsors.
Both versions will be unlocked automatically in Django-salesforce 5.1 when a key will be
required for Django 5.1. Use with pre-release Django versions is free.
Quick Start
-----------
Install, configure a Salesforce connection, create a Salesforce model and run.
1. **Install** django-salesforce: ``pip install django-salesforce``
2. Add a Salesforce **connection** to your ``DATABASES`` **setting**::
'salesforce': {
'ENGINE': 'salesforce.backend',
'CONSUMER_KEY': '', # 'client_id' in OAuth2 terminology
'CONSUMER_SECRET': '', # 'client_secret'
'USER': '',
'PASSWORD': '',
'HOST': 'https://test.salesforce.com',
}
In the example above, all fields should be populated as follows:
* ``CONSUMER_KEY`` and ``CONSUMER_SECRET`` values are for the app used to
connect to your Salesforce account. Instructions for how get these are in
the Salesforce REST API Documentation. Key and secret can be created on
web by:
- SalesForce **Lightning** > Setup > Apps > App Manager > New Connected App or by
Salesforce **Classic** > Setup > App Setup > Create > Apps > Connected apps >
New.
- Click "Enable OAuth Settings" in API, then select "Access and manage
your data (api)" from available OAuth Scopes.
- Other red marked fields must be filled, but are not relevant for Django
with password authentication. ("Callback URL" should be a safe URL
that maybe doesn't exist now, but its path is under your control and
doesn't redirect. This would be important if you activate other OAuth
mode later.)
- SalesForce **Lightning** > Setup > Identity > OAuth and OpenID Connect Settings: Ensure that the "Allow OAuth Username-Password Flows" option is checked. This is important if you use USER/PASSWORD below, and is not the default since Summer '23.
* ``USER`` is the username used to connect.
* ``PASSWORD`` is a concatenation of the user's password and security token.
Security token can be set by My Settings / Personal / Reset My Security Token
or an new token is received by email after every password change.
Security token can be omitted if the local IP address has been
whitelisted in Security Controls / Network Access.
* ``HOST`` is ``https://test.salesforce.com`` to access a sandbox, or
``https://login.salesforce.com`` to access production or your domain
``https://MyDomainName.my.salesforce.com``.
3. Add ``salesforce.router.ModelRouter`` to your ``DATABASE_ROUTERS``
setting::
DATABASE_ROUTERS = [
"salesforce.router.ModelRouter"
]
(This is important for switching between 'salesforce' database for
models derived from SalesforceModel and 'default' database for normal models
with tables created by migrations, especially for 'django.contrib'.)
4. Add the ``salesforce`` app to your ``INSTALLED_APPS`` setting::
INSTALLED_APPS = {
"django.contrib.auth",
"django.contrib.contenttypes",
...
...
"salesforce"
}
(This is necessary for running Salesforce extensions in the command
``inspectdb --database=salesforce`` in development, otherwise it is
not important.)
5. Add a setting ``DJSF_LICENSE_KEY = "Your Name or Company / email //our.signature=="``
if you need it for Django 5.0 or 4.2.
6. **Verify** that everything important is configured correctly by running
the command ``python manage.py check --database=salesforce``.
You get eventualy the important information about problems related to the previous
steps. (clearly without tracebacks)
That is useful again after you define your database model or if you customize your
configuration later and e.g. you configure multiple Salesforce databases.
7. Define a **model** that extends ``salesforce.models.Model`` (alias ``SalesforceModel``)
or export the complete SF schema by ``python manage.py inspectdb --database=salesforce``
and simplify it to what you need. The full models file is about 1.5 MB with 500 models
and the export takes 2 minutes, but it is a valid models module that works without
modification. The output of command ``inspectdb`` can be restricted by a list
of table_names on the command line, but also ForeignKey fields to omitted models
must be pruned to get a valid complete small model.
8. **You're all done!** Just use your model like a normal Django model.
If an error occurs in a request to Salesforce, review the received error message
that is exactly copied between braces ``{...}`` from the
Salesforce response to a Python exception to assist debugging.
See also: `Information on settings up Salesforce connected apps
<https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm>`_
if necessary.
**Note about permissions**: Administrator profile are only required to run
the full suite of unit tests of this framework; otherwise, as long as
the account has rights to read or modify the chosen object, everything
should work properly. Introspection by ``inspectdb`` doesn't require any
additional object permissions.
Optional small features
-----------------------
- **Salesforce alias** If you want to use another name for your Salesforce DB
connection, define ``SALESFORCE_DB_ALIAS`` in your settings file::
SALESFORCE_DB_ALIAS = 'salesforce' # default
- **Timeout settings** To override the default timeout of 15 seconds,
define ``SALESFORCE_QUERY_TIMEOUT`` in your settings file.
It can be one number or better a tuple with a short value for connection
timeout and a longer value that includes time for running a query.
It never need be longer than 30 seconds::
SALESFORCE_QUERY_TIMEOUT = (4, 15) # default (connect timeout, data timeout)
- **Automatic stupid admin** Create a normal Django ``admin.py`` module for your Salesforce models
and you can register a minimalistic admin for all omitted Admin classes::
from salesforce.testrunner.example.universal_admin import register_omitted_classes
# some admin classes that you wrote manually yet
# ...
# end of file
register_omitted_classes(your_application.models)
This is a rudimentary way to verify that every model works in a sandbox, before
hand-writing all admin classes. (Foreign keys to huge tables in the production
require a customized admin e.g. with search widgets.)
- **Lazy connect** By default, the Django ORM connects to all DBs at startup. To delay
SFDC connections until they are actually required, define ``SF_LAZY_CONNECT=True``
in your settings file. Be careful when using this setting; since it won't fail during
the application boot, it's possible for a bad password to be sent repeatedly,
requiring an account reset to fix.
- **Configurable Primary Key**
Salesforce doesn't allow you to define custom primary keys, so django-salesforce
will add them automatically in all cases. You can override only capitalization and use
a primary key ``Id`` by configuring ``SF_PK='Id'`` in your project settings
if you prefer Salesforce capitalized field name conventions instead of Django
default ``id``.
Advanced usage
--------------
- **Multiple Inheritance from Abstract Models** - Many Salesforce models use
the same sets of fields, but using a single inheritance tree would be too
complicated and fragile. Proxy models and mixins are also supported.
- **Testing** - By default, tests will be run against the SFDC connection
specified in settings.py, which will substantially increase testing time.
One way to speed this up is to change the SALESFORCE_DB_ALIAS to point to
another DB connection (preferably SQLite) during testing using the
``TEST`` settings variable. Such simple tests can run without any network
access. Django unit tests without SalesforceModel are fast everytimes.
Special read only fields (with ``sf_read_only=...``) that are updated only by SFDC
e.g. ``last_modified_date`` need more parameters to be possible to save them
into an alternate database, e.g. by ``auto_now=True`` or to play with
``null=True`` or ``default=...``.
- **Multiple SFDC connections** - In most cases, a single connection is all
that most apps require, so the default DB connection to use for Salesforce
is defined by the ``SALESFORCE_DB_ALIAS`` settings variable. This behavior
can be also configured by ``DATABASE_ROUTERS``, replacing the use of
salesforce.router.ModelRouter.
- **Non SF databases** - If ``SALESFORCE_DB_ALIAS`` is set to a conventional
database, the tables defined by the SF models will be created by ``migrate``. This
behavior can be disabled by adding a Meta class with ``managed=False``.
- **Custom Managers** - When creating a custom manager for a model, the manager
must be a descendant of ``salesforce.manager.SalesforceManager``.
In most cases, switching DB connections with ``.using(alias).`` will be
sufficient, but if you need to call a method on your custom manager, you should
instead use ``.db_manager(alias)`` to select a DB while returning the correct
manager, e.g. ``Contact.objects.db_manager(alias).my_manager(params...)``
- **Automatic Field Naming** - Most of database columns names can be automatically
deduced from Django field name, if no ``db_column`` is specified::
last_name = models.CharField(max_length=80) # db_column='LastName'
FirstName = models.CharField(max_length=80) # db_column='FirstName'
my_bool = models.BooleanField(custom=True) # db_column='MyBool__c'
Fields named with an upper case character are never modified, except for the
addition of the namespace prefix or the '__c' suffix for custom fields.
If you want models with minimal db_column then read
`Running inspectdb <https://github.com/django-salesforce/django-salesforce/wiki/Introspection-and-Special-Attributes-of-Fields#running-inspectdb>`__.
- **Query deleted objects** - Deleted objects that are in trash bin are
not selected by a normal queryset, but if a special method ``query_all``
is used then also deleted objects are searched.
If a trash bin is supported by the model then a boolean field ``IsDeleted``
can be in the model and it is possible to select only deleted objects ::
deleted_list = list(Lead.objects.filter(IsDeleted=True).query_all())
- **Migrations** - Migrations can be used for an alternate test database
with SalesforceModel. Then all tables must have Meta options ``db_table``
and fields must have option ``db_column``, which is done by ``inspectdb``
with default settings. Models exported by introspection ``inspectdb``
do not specify the option ``managed`` because the default value is True.
There is probably no reason now to collect old migrations of an application
that uses only SalesforceModel if they are related to data stored only in Salesforce.
Such old migrations can be easily deleted and a new initial migration can be
created again if it would be necessary for offline tests if that migrations
directory seems big and obsoleted.
- **Exceptions** - Custom exceptions instead of standard Django database
exceptions are raised by Django-Salesforce to get more useful information.
General exceptions are ``SalesforceError`` or a more general custom
``DatabaseError``. They can be imported from ``salesforce.dbapi.exceptions``
if database errors should be handled specifically in your app.
Foreign Key Support
-------------------
Foreign key relationships should work as expected, especially relationships
from child to parents are well supported in querysets, but mapping
Salesforce SOQL to a purely-relational mapper is a leaky abstraction
and some knowledge about limitations of SOQL is useful. Some rejected
queries should be usually rewritten to two simpler queries.
For the gory details, see
`Foreign Key Support <https://github.com/django-salesforce/django-salesforce/wiki/Foreign-Key-Support>`__
on the Django-Salesforce wiki.
Introspection and special attributes of fields
----------------------------------------------
Some Salesforce fields can not be fully used without special attributes, namely
read-only fields and some default values. Further details can be found in
`Introspection and Special Attributes of Fields <https://github.com/django-salesforce/django-salesforce/wiki/Introspection-and-Special-Attributes-of-Fields>`__
Caveats
-------
The ultimate goal of development of this package is to support reasonable
new features of the Salesforce platform and of new Django versions,
but for now here are the potential pitfalls and unimplemented operations:
- **Large Objects** — Since the entire result set needs to be transferred
over HTTP, and since it's common to have extremely high column counts
on full object queries, it's assumed that users will create models that
are specific to their individual applications' needs. It is especially
important if migrations should be created. Migrations on the full models
module are really slow. (Models that have been included with this library are
very simplified only for example and documentation purposes and for tests.)
- **Inheritance** — When using the default router, all models Salesforce
must extend salesforce.models.SalesforceModel. The model router checks
for this to determine which models to handle through the Salesforce
connection.
- **Database Migrations** — ``migrate`` will create new tables only in non-SF
databases (useful for unit tests); SFDC tables are assumed to already
exist with the appropriate permissions. (A very incomplete implementation
of migrations in Salesforce has been in a development repository around
for two years. I am satisfied for my purposes. Development for better
general usability is the main reason why am I trying to get sponsors.)
- **Unsupported methods**: Queryset methods ``union()``, ``difference()``,
``intersection()`` and ``distinct()``
are e.g. not supported because SOQL doesn't support corresponding operators:
UNION, EXCEPT, INTERSECT and DISTINCT.
Backwards-incompatible changes
------------------------------
The last most important:
- v5.0.2: Removed support for Python 3.7 and Django 2.0
- v4.2: Some new features or versions implemented after June 2023 can require a license key
(sponsorship) or to accept the AGPL license. (AGPL is fine for exclusive open source
contribution or for education, but impossible if you do not share all your
source codes.)
Removed support for Python 3.6
Raw data
{
"_id": null,
"home_page": "https://github.com/django-salesforce/django-salesforce",
"name": "django-salesforce",
"maintainer": "Phil Christensen",
"docs_url": null,
"requires_python": null,
"maintainer_email": "phil@bubblehouse.org",
"keywords": "django salesforce orm backend",
"author": "Hynek Cernoch",
"author_email": "hynek@sdb.cz",
"download_url": "https://files.pythonhosted.org/packages/29/04/2463a04b59e53e3571471d072e173f7fa99f006c61e53c5fb24ba1733ec5/django-salesforce-5.0.2.tar.gz",
"platform": null,
"description": "django-salesforce\n=================\n\n.. image:: https://github.com/django-salesforce/django-salesforce/actions/workflows/main.yml/badge.svg\n :target: https://github.com/django-salesforce/django-salesforce/actions/workflows/main.yml\n\n.. image:: https://badge.fury.io/py/django-salesforce.svg\n :target: https://pypi.python.org/pypi/django-salesforce\n\n.. image:: https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg\n :target: https://www.python.org/\n\n.. image:: https://img.shields.io/badge/Django-2.1%2C%202.2%20%7C%203.0%2C%203.1%20%2C%203.2%20%7C%204.0%2C%204.1%2C%204.2%20%7C%205.0-blue.svg\n :target: https://www.djangoproject.com/\n\nThis library allows you to load, edit and query the objects in any Salesforce instance\nusing Django models. The integration is fairly complete, and generally seamless\nfor most uses. It works by integrating with the Django ORM, allowing access to\nthe objects in your SFDC instance (Salesforce .com) as if they were in a\ntraditional database.\n\nPython 3.8 to 3.12, Django 2.1 to 5.0. (Tested also with Python 3.13b1)\n\nUse with Django 5.0 or 4.2(LTS) currently requires an enteprise license key DJSF_LICENSE_KEY\nuntil August 2024 unless you accept the AGPL license and install our otherwise identical\npackage \"django-salesforce-agpl\" instead. The license keys are available to sponsors.\nBoth versions will be unlocked automatically in Django-salesforce 5.1 when a key will be\nrequired for Django 5.1. Use with pre-release Django versions is free.\n\n\nQuick Start\n-----------\n\nInstall, configure a Salesforce connection, create a Salesforce model and run.\n\n1. **Install** django-salesforce: ``pip install django-salesforce``\n\n2. Add a Salesforce **connection** to your ``DATABASES`` **setting**::\n\n 'salesforce': {\n 'ENGINE': 'salesforce.backend',\n 'CONSUMER_KEY': '', # 'client_id' in OAuth2 terminology\n 'CONSUMER_SECRET': '', # 'client_secret'\n 'USER': '',\n 'PASSWORD': '',\n 'HOST': 'https://test.salesforce.com',\n }\n\n In the example above, all fields should be populated as follows:\n\n * ``CONSUMER_KEY`` and ``CONSUMER_SECRET`` values are for the app used to\n connect to your Salesforce account. Instructions for how get these are in\n the Salesforce REST API Documentation. Key and secret can be created on\n web by:\n\n - SalesForce **Lightning** > Setup > Apps > App Manager > New Connected App or by\n Salesforce **Classic** > Setup > App Setup > Create > Apps > Connected apps >\n New. \n - Click \"Enable OAuth Settings\" in API, then select \"Access and manage\n your data (api)\" from available OAuth Scopes.\n - Other red marked fields must be filled, but are not relevant for Django\n with password authentication. (\"Callback URL\" should be a safe URL\n that maybe doesn't exist now, but its path is under your control and\n doesn't redirect. This would be important if you activate other OAuth\n mode later.)\n - SalesForce **Lightning** > Setup > Identity > OAuth and OpenID Connect Settings: Ensure that the \"Allow OAuth Username-Password Flows\" option is checked. This is important if you use USER/PASSWORD below, and is not the default since Summer '23.\n * ``USER`` is the username used to connect.\n * ``PASSWORD`` is a concatenation of the user's password and security token.\n Security token can be set by My Settings / Personal / Reset My Security Token\n or an new token is received by email after every password change.\n Security token can be omitted if the local IP address has been\n whitelisted in Security Controls / Network Access.\n * ``HOST`` is ``https://test.salesforce.com`` to access a sandbox, or\n ``https://login.salesforce.com`` to access production or your domain\n ``https://MyDomainName.my.salesforce.com``.\n\n3. Add ``salesforce.router.ModelRouter`` to your ``DATABASE_ROUTERS``\n setting::\n\n DATABASE_ROUTERS = [\n \"salesforce.router.ModelRouter\"\n ]\n\n (This is important for switching between 'salesforce' database for\n models derived from SalesforceModel and 'default' database for normal models\n with tables created by migrations, especially for 'django.contrib'.)\n\n4. Add the ``salesforce`` app to your ``INSTALLED_APPS`` setting::\n\n INSTALLED_APPS = {\n \"django.contrib.auth\",\n \"django.contrib.contenttypes\",\n ...\n ...\n \"salesforce\"\n }\n\n (This is necessary for running Salesforce extensions in the command\n ``inspectdb --database=salesforce`` in development, otherwise it is\n not important.)\n\n5. Add a setting ``DJSF_LICENSE_KEY = \"Your Name or Company / email //our.signature==\"``\n if you need it for Django 5.0 or 4.2.\n\n6. **Verify** that everything important is configured correctly by running\n the command ``python manage.py check --database=salesforce``.\n You get eventualy the important information about problems related to the previous\n steps. (clearly without tracebacks)\n\n That is useful again after you define your database model or if you customize your\n configuration later and e.g. you configure multiple Salesforce databases.\n\n7. Define a **model** that extends ``salesforce.models.Model`` (alias ``SalesforceModel``)\n or export the complete SF schema by ``python manage.py inspectdb --database=salesforce``\n and simplify it to what you need. The full models file is about 1.5 MB with 500 models\n and the export takes 2 minutes, but it is a valid models module that works without\n modification. The output of command ``inspectdb`` can be restricted by a list\n of table_names on the command line, but also ForeignKey fields to omitted models\n must be pruned to get a valid complete small model.\n\n8. **You're all done!** Just use your model like a normal Django model.\n\n If an error occurs in a request to Salesforce, review the received error message\n that is exactly copied between braces ``{...}`` from the\n Salesforce response to a Python exception to assist debugging.\n\n See also: `Information on settings up Salesforce connected apps\n <https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm>`_\n if necessary.\n\n **Note about permissions**: Administrator profile are only required to run\n the full suite of unit tests of this framework; otherwise, as long as\n the account has rights to read or modify the chosen object, everything\n should work properly. Introspection by ``inspectdb`` doesn't require any\n additional object permissions.\n\n\nOptional small features\n-----------------------\n\n- **Salesforce alias** If you want to use another name for your Salesforce DB\n connection, define ``SALESFORCE_DB_ALIAS`` in your settings file::\n\n SALESFORCE_DB_ALIAS = 'salesforce' # default\n\n- **Timeout settings** To override the default timeout of 15 seconds,\n define ``SALESFORCE_QUERY_TIMEOUT`` in your settings file.\n It can be one number or better a tuple with a short value for connection\n timeout and a longer value that includes time for running a query.\n It never need be longer than 30 seconds::\n\n SALESFORCE_QUERY_TIMEOUT = (4, 15) # default (connect timeout, data timeout)\n\n- **Automatic stupid admin** Create a normal Django ``admin.py`` module for your Salesforce models\n and you can register a minimalistic admin for all omitted Admin classes::\n\n from salesforce.testrunner.example.universal_admin import register_omitted_classes\n # some admin classes that you wrote manually yet\n # ...\n # end of file\n register_omitted_classes(your_application.models)\n\n This is a rudimentary way to verify that every model works in a sandbox, before\n hand-writing all admin classes. (Foreign keys to huge tables in the production\n require a customized admin e.g. with search widgets.)\n \n- **Lazy connect** By default, the Django ORM connects to all DBs at startup. To delay\n SFDC connections until they are actually required, define ``SF_LAZY_CONNECT=True``\n in your settings file. Be careful when using this setting; since it won't fail during\n the application boot, it's possible for a bad password to be sent repeatedly,\n requiring an account reset to fix.\n\n- **Configurable Primary Key**\n Salesforce doesn't allow you to define custom primary keys, so django-salesforce\n will add them automatically in all cases. You can override only capitalization and use\n a primary key ``Id`` by configuring ``SF_PK='Id'`` in your project settings\n if you prefer Salesforce capitalized field name conventions instead of Django\n default ``id``.\n\nAdvanced usage\n--------------\n- **Multiple Inheritance from Abstract Models** - Many Salesforce models use\n the same sets of fields, but using a single inheritance tree would be too\n complicated and fragile. Proxy models and mixins are also supported.\n\n- **Testing** - By default, tests will be run against the SFDC connection\n specified in settings.py, which will substantially increase testing time.\n\n One way to speed this up is to change the SALESFORCE_DB_ALIAS to point to\n another DB connection (preferably SQLite) during testing using the\n ``TEST`` settings variable. Such simple tests can run without any network\n access. Django unit tests without SalesforceModel are fast everytimes.\n Special read only fields (with ``sf_read_only=...``) that are updated only by SFDC\n e.g. ``last_modified_date`` need more parameters to be possible to save them\n into an alternate database, e.g. by ``auto_now=True`` or to play with\n ``null=True`` or ``default=...``.\n \n- **Multiple SFDC connections** - In most cases, a single connection is all\n that most apps require, so the default DB connection to use for Salesforce\n is defined by the ``SALESFORCE_DB_ALIAS`` settings variable. This behavior\n can be also configured by ``DATABASE_ROUTERS``, replacing the use of\n salesforce.router.ModelRouter.\n\n- **Non SF databases** - If ``SALESFORCE_DB_ALIAS`` is set to a conventional\n database, the tables defined by the SF models will be created by ``migrate``. This\n behavior can be disabled by adding a Meta class with ``managed=False``.\n\n- **Custom Managers** - When creating a custom manager for a model, the manager\n must be a descendant of ``salesforce.manager.SalesforceManager``.\n \n In most cases, switching DB connections with ``.using(alias).`` will be\n sufficient, but if you need to call a method on your custom manager, you should\n instead use ``.db_manager(alias)`` to select a DB while returning the correct\n manager, e.g. ``Contact.objects.db_manager(alias).my_manager(params...)``\n\n- **Automatic Field Naming** - Most of database columns names can be automatically\n deduced from Django field name, if no ``db_column`` is specified::\n\n last_name = models.CharField(max_length=80) # db_column='LastName'\n FirstName = models.CharField(max_length=80) # db_column='FirstName'\n my_bool = models.BooleanField(custom=True) # db_column='MyBool__c'\n \n Fields named with an upper case character are never modified, except for the\n addition of the namespace prefix or the '__c' suffix for custom fields.\n If you want models with minimal db_column then read\n `Running inspectdb <https://github.com/django-salesforce/django-salesforce/wiki/Introspection-and-Special-Attributes-of-Fields#running-inspectdb>`__.\n\n- **Query deleted objects** - Deleted objects that are in trash bin are\n not selected by a normal queryset, but if a special method ``query_all``\n is used then also deleted objects are searched.\n If a trash bin is supported by the model then a boolean field ``IsDeleted``\n can be in the model and it is possible to select only deleted objects ::\n\n deleted_list = list(Lead.objects.filter(IsDeleted=True).query_all())\n\n- **Migrations** - Migrations can be used for an alternate test database\n with SalesforceModel. Then all tables must have Meta options ``db_table``\n and fields must have option ``db_column``, which is done by ``inspectdb``\n with default settings. Models exported by introspection ``inspectdb``\n do not specify the option ``managed`` because the default value is True.\n\n There is probably no reason now to collect old migrations of an application\n that uses only SalesforceModel if they are related to data stored only in Salesforce.\n Such old migrations can be easily deleted and a new initial migration can be\n created again if it would be necessary for offline tests if that migrations\n directory seems big and obsoleted.\n\n- **Exceptions** - Custom exceptions instead of standard Django database\n exceptions are raised by Django-Salesforce to get more useful information.\n General exceptions are ``SalesforceError`` or a more general custom\n ``DatabaseError``. They can be imported from ``salesforce.dbapi.exceptions``\n if database errors should be handled specifically in your app.\n\nForeign Key Support\n-------------------\nForeign key relationships should work as expected, especially relationships\nfrom child to parents are well supported in querysets, but mapping\nSalesforce SOQL to a purely-relational mapper is a leaky abstraction\nand some knowledge about limitations of SOQL is useful. Some rejected\nqueries should be usually rewritten to two simpler queries.\nFor the gory details, see\n`Foreign Key Support <https://github.com/django-salesforce/django-salesforce/wiki/Foreign-Key-Support>`__\non the Django-Salesforce wiki.\n\nIntrospection and special attributes of fields\n----------------------------------------------\nSome Salesforce fields can not be fully used without special attributes, namely\nread-only fields and some default values. Further details can be found in\n`Introspection and Special Attributes of Fields <https://github.com/django-salesforce/django-salesforce/wiki/Introspection-and-Special-Attributes-of-Fields>`__\n\nCaveats\n-------\n\nThe ultimate goal of development of this package is to support reasonable\nnew features of the Salesforce platform and of new Django versions,\nbut for now here are the potential pitfalls and unimplemented operations:\n\n- **Large Objects** \u2014 Since the entire result set needs to be transferred\n over HTTP, and since it's common to have extremely high column counts\n on full object queries, it's assumed that users will create models that\n are specific to their individual applications' needs. It is especially\n important if migrations should be created. Migrations on the full models\n module are really slow. (Models that have been included with this library are\n very simplified only for example and documentation purposes and for tests.)\n- **Inheritance** \u2014 When using the default router, all models Salesforce\n must extend salesforce.models.SalesforceModel. The model router checks\n for this to determine which models to handle through the Salesforce\n connection.\n- **Database Migrations** \u2014 ``migrate`` will create new tables only in non-SF\n databases (useful for unit tests); SFDC tables are assumed to already\n exist with the appropriate permissions. (A very incomplete implementation\n of migrations in Salesforce has been in a development repository around\n for two years. I am satisfied for my purposes. Development for better\n general usability is the main reason why am I trying to get sponsors.)\n\n- **Unsupported methods**: Queryset methods ``union()``, ``difference()``,\n ``intersection()`` and ``distinct()``\n are e.g. not supported because SOQL doesn't support corresponding operators:\n UNION, EXCEPT, INTERSECT and DISTINCT.\n\nBackwards-incompatible changes\n------------------------------\n\nThe last most important:\n\n- v5.0.2: Removed support for Python 3.7 and Django 2.0\n\n- v4.2: Some new features or versions implemented after June 2023 can require a license key\n (sponsorship) or to accept the AGPL license. (AGPL is fine for exclusive open source\n contribution or for education, but impossible if you do not share all your\n source codes.)\n Removed support for Python 3.6\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "a Salesforce backend for Django's ORM",
"version": "5.0.2",
"project_urls": {
"Homepage": "https://github.com/django-salesforce/django-salesforce"
},
"split_keywords": [
"django",
"salesforce",
"orm",
"backend"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a89c90c7633c821084ab1756467ed7a7cfb9abc3f49305e00e675f844e0648d",
"md5": "ca6670f438eb1918a440ae97d2be4269",
"sha256": "e6ca0303401912801ba9c15c69408dc3b1bb1072d66966b1a57180cabd3b72d2"
},
"downloads": -1,
"filename": "django_salesforce-5.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca6670f438eb1918a440ae97d2be4269",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 146327,
"upload_time": "2024-05-27T14:35:46",
"upload_time_iso_8601": "2024-05-27T14:35:46.454550Z",
"url": "https://files.pythonhosted.org/packages/2a/89/c90c7633c821084ab1756467ed7a7cfb9abc3f49305e00e675f844e0648d/django_salesforce-5.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "29042463a04b59e53e3571471d072e173f7fa99f006c61e53c5fb24ba1733ec5",
"md5": "118bb20cc95577406153aee0f005e617",
"sha256": "ae497aea96de0bb9c5e2d54ac97ed58d62068b1d68e5170f2d71f4dbfe008130"
},
"downloads": -1,
"filename": "django-salesforce-5.0.2.tar.gz",
"has_sig": false,
"md5_digest": "118bb20cc95577406153aee0f005e617",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 195021,
"upload_time": "2024-05-27T14:35:48",
"upload_time_iso_8601": "2024-05-27T14:35:48.607977Z",
"url": "https://files.pythonhosted.org/packages/29/04/2463a04b59e53e3571471d072e173f7fa99f006c61e53c5fb24ba1733ec5/django-salesforce-5.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-27 14:35:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "django-salesforce",
"github_project": "django-salesforce",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "django-salesforce"
}
JSON
