<commit_before>django-salesforce
=================

.. image:: https://travis-ci.org/django-salesforce/django-salesforce.svg?branch=master
   :target: https://travis-ci.org/django-salesforce/django-salesforce

This library allows you to load and edit 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 2.7.9+, 3.4, 3.5, Django 1.7, 1.8.4+, 1.9., 1.10 are supported.
Currently problematic: raw queries, values_list() and values() methods.
Django 1.10 is currently supported without values(), values_list(), defer(),
some raw() methods and without makemigrations.
The full support of 1.10 can be still expected during August 2016.
(Make it a footnote:
The lowest Python versions are restricted by TLSv1.1 support that is
required for development sites now. PyPy probably still works, but it
seems not easy to get a precompiled version linked to a new libssl.)

Quick Start
-----------

1. Install django-salesforce: ``pip install django-salesforce``

2. Add the ``salesforce`` app to your ``INSTALLED_APPS`` setting::

    INSTALLED_APPS = {
        "django.contrib.auth",
        "django.contrib.contenttypes",
        ...
        ...
        "salesforce"
    }


3. Add a salesforce connection to your ``DATABASES`` setting::

    'salesforce': {
        'ENGINE': 'salesforce.backend',
        'CONSUMER_KEY': '',
        'CONSUMER_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 web > 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.
   * ``USER`` is the username used to connect.
   * ``PASSWORD`` is a concatenation of the user's password and security token.
     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 the sandbox, or
     ``https://login.salesforce.com`` to access production.

   If an error message is received while connecting, review the error received.
   Everything in the error message between ``{...}`` is exactly copied from the
   Salesforce error message to assist debugging.

   See also: `Information on settings up Salesforce connected apps
   <https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm>`_.

   **Note about permissions**: Everything for a project can work under
   restricted Salesforce user account if it has access to objects in your
   models. Introspection (inspectdb) doesn't require any permissions. Running
   tests for django_salesforce requires many permissions or Administrator
   account for sandbox.

4. Add ``salesforce.router.ModelRouter`` to your ``DATABASE_ROUTERS``
   setting::

    DATABASE_ROUTERS = [
        "salesforce.router.ModelRouter"
    ]

5. Define a model that extends ``salesforce.models.Model`` or export the
   complete SF schema by ``python manage.py inspectdb --database=salesforce``
   and simplify it to what you need.

6. **(optional)** To override the default timeout of 15 seconds,
   define ``SALESFORCE_QUERY_TIMEOUT`` in your settings file::

    SALESFORCE_QUERY_TIMEOUT = 15  # default

7. **(optional)** 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

8. You're all done! Just use your model like a normal Django model.

9. **(optional)** Create a normal Django ``admin.py`` module for your Salesforce model::

    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 sandbox, before
   handwritting all admin classes. (Foreign keys to huge tables in the production
   require customized admins e.g. with search widgets.)
    
10. **(optional)** 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.

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 capitalization and use
primary key ``id`` by configuring ``SF_PK='id'`` in your project settings. The previous
capitalization of ``Id`` is only for old projects, but it will stay as the default
variant until ``django-salesforce>=0.5``.

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<commit_msg>Small edits for README language<commit_after>django-salesforce
=================

.. image:: https://travis-ci.org/django-salesforce/django-salesforce.svg?branch=master
   :target: https://travis-ci.org/django-salesforce/django-salesforce

This library allows you to load and edit 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 2.7.9+, 3.4, 3.5, Django 1.7, 1.8.4+, 1.9., 1.10 are supported with
some limitations on raw queries, values_list() and values() methods.

Django 1.10 is currently supported without values(), values_list(), defer(),
some raw() methods and without makemigrations. Full support of 1.10 is
expected near the end of Q3 or beginning of Q4 in 2016.

Pre-2.7.9 Python versions don't have the required TLS 1.1 support to use
both production and sandbox Salesforce instances. PyPy may still work,
but currently it's a challenge to get a PyPy build linked to a recent
version of libssl.

Quick Start
-----------

1. Install django-salesforce: ``pip install django-salesforce``

2. Add the ``salesforce`` app to your ``INSTALLED_APPS`` setting::

    INSTALLED_APPS = {
        "django.contrib.auth",
        "django.contrib.contenttypes",
        ...
        ...
        "salesforce"
    }


3. Add a salesforce connection to your ``DATABASES`` setting::

    'salesforce': {
        'ENGINE': 'salesforce.backend',
        'CONSUMER_KEY': '',
        'CONSUMER_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 web > 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.
   * ``USER`` is the username used to connect.
   * ``PASSWORD`` is a concatenation of the user's password and security token.
     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.

   If an error message is received while connecting, review the error received.
   Everything in the error message between ``{...}`` is exactly copied from the
   Salesforce error message to assist debugging.

   See also: `Information on settings up Salesforce connected apps
   <https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm>`_.

   **Note about permissions**: Everything for a project can work under
   restricted Salesforce user account if it has access to objects in your
   models. Introspection (inspectdb) doesn't require any permissions. Running
   tests for django_salesforce requires many permissions or Administrator
   account for sandbox.
   
   **Note about permissions**: Administrator rights are only required to run
   the full suite of unit tests; otherwise, as long as the account has rights to
   read or modify the chosen object, everything should work properly.

4. Add ``salesforce.router.ModelRouter`` to your ``DATABASE_ROUTERS``
   setting::

    DATABASE_ROUTERS = [
        "salesforce.router.ModelRouter"
    ]

5. Define a model that extends ``salesforce.models.Model`` or export the
   complete SF schema by ``python manage.py inspectdb --database=salesforce``
   and simplify it to what you need.

6. **(optional)** To override the default timeout of 15 seconds,
   define ``SALESFORCE_QUERY_TIMEOUT`` in your settings file::

    SALESFORCE_QUERY_TIMEOUT = 15  # default

7. **(optional)** 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

8. You're all done! Just use your model like a normal Django model.

9. **(optional)** Create a normal Django ``admin.py`` module for your Salesforce model::

    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 sandbox, before
   hand-writing all admin classes. (Foreign keys to huge tables in the production
   require customized admins e.g. with search widgets.)
    
10. **(optional)** 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.

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 capitalization and use
primary key ``id`` by configuring ``SF_PK='id'`` in your project settings. The previous
capitalization of ``Id`` is only for old projects, but it will stay as the default
variant until ``django-salesforce>=0.5``.

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
{'fraction_non_alphanumeric': 0.08836351441985245, 'fraction_numerical': 0.00813212608987257, 'mean_word_length': 3.5565317035905273, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 19, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5651272', 'n_tokens_mistral': 3361, 'n_tokens_neox': 3142, 'n_words': 1465}