tomtoolkit 3.0.0a12__tar.gz → 3.0.1__tar.gz

tomtoolkit-3.0.1/.git/FETCH_HEAD

@@ -0,0 +1 @@
+d8ccf933fe2e40c5e92eeb9ee11251009f25331b		'd8ccf933fe2e40c5e92eeb9ee11251009f25331b' of https://github.com/TOMToolkit/tom_base

tomtoolkit-3.0.1/.git/HEAD

@@ -0,0 +1 @@
+d8ccf933fe2e40c5e92eeb9ee11251009f25331b

tomtoolkit-3.0.1/.git/config

@@ -0,0 +1,12 @@
+[core]
+	repositoryformatversion = 0
+	filemode = true
+	bare = false
+	logallrefupdates = true
+[remote "origin"]
+	url = https://github.com/TOMToolkit/tom_base
+	fetch = +refs/heads/*:refs/remotes/origin/*
+[gc]
+	auto = 0
+[http "https://github.com/"]
+	extraheader = AUTHORIZATION: basic eC1hY2Nlc3MtdG9rZW46Z2hzXzE1MzY4X2V5SmhiR2NpT2lKRlV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpoZFdRaU9pSmhkWFJvYm1RaUxDSmpkSGdpT2lKTVpGZHRlbVZVYTJKcGFFWlNOVE0yVERVeFVUY3hVRjkzU1V4R1RrSXpZbHB2VEVKMU5YSktjbUZsTWt0MVdrNWpWeTAyUjBobklpd2laWGh3SWpveE56ZzNOams0TURFMkxDSnBZWFFpT2pFM09EYzJPVFEwTVRZc0ltbHpjeUk2SW1kcGRHaDFZaUlzSW1wMGFTSTZJalZpTnpoalpHUXdMV05oWW1ZdE5HTTNNUzFoTTJWakxUWmxNRGRtWmpVMVpXRTVPQ0lzSW5abGNpSTZNMzAuTkNBaFM4Um5FcHdrMVRINnk0bkhZZWY4Ynp5SW1iQ0puVEl1WGJrVUtMSURuVXdCeTUwQTN6YUVlUDFkWmo1V1I2WU50TzRqaHpWNFpFNk9BakozUEE=

tomtoolkit-3.0.1/.git/logs/HEAD

@@ -0,0 +1 @@
+0000000000000000000000000000000000000000 d8ccf933fe2e40c5e92eeb9ee11251009f25331b runner <runner@runnervm76f27.c41v2zfaraieda3n4uxiuojluc.phxx.internal.cloudapp.net> 1787694421 +0000	checkout: moving from master to refs/tags/3.0.1

tomtoolkit-3.0.1/.git/refs/tags/3.0.1

@@ -0,0 +1 @@
+d8ccf933fe2e40c5e92eeb9ee11251009f25331b

tomtoolkit-3.0.1/.git/shallow

@@ -0,0 +1 @@
+d8ccf933fe2e40c5e92eeb9ee11251009f25331b

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tomtoolkit
-Version: 3.0.0a12
+Version: 3.0.1
 Summary: TOM Toolkit and base modules
 License-Expression: GPL-3.0-only
 License-File: LICENSE
@@ -22,26 +22,26 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Dist: alerce (>=2.0,<3.0)
+Requires-Dist: alerce (>=2.3.1,<3.0)
 Requires-Dist: astroplan (>=0.8,<0.11)
 Requires-Dist: astropy (>=5.3.3,<6) ; python_version < "3.10"
 Requires-Dist: astropy (>=5.3.3,<8) ; python_version >= "3.10"
 Requires-Dist: astroquery (<1)
 Requires-Dist: beautifulsoup4 (<5)
 Requires-Dist: crispy-bootstrap5 (<2027)
-Requires-Dist: cryptography (<=48.0.1)
-Requires-Dist: django (>=5,<6)
+Requires-Dist: cryptography (<=50.0.0)
+Requires-Dist: django (>=5.2.17,<6)
 Requires-Dist: django-bootstrap5 (<27)
 Requires-Dist: django-contrib-comments (>=2.0,<3.0)
-Requires-Dist: django-crispy-forms (>=2.0,<3.0)
+Requires-Dist: django-crispy-forms (>=2.7,<3.0)
 Requires-Dist: django-extensions (>=3.0.0,<4.0.0)
 Requires-Dist: django-filter (>=23,<25)
 Requires-Dist: django-gravatar2 (>=1.0.0,<2.0.0)
 Requires-Dist: django-guardian (>=2.0.0,<3.0.0)
-Requires-Dist: django-htmx (>=1.0.0,<2.0.0)
+Requires-Dist: django-htmx (>=1.29.0,<2.0.0)
 Requires-Dist: django-tables2 (>=3.0,<4)
 Requires-Dist: django-tasks (>=0.6.1,<0.7.0)
-Requires-Dist: djangorestframework (>=3.15,<4)
+Requires-Dist: djangorestframework (>=3.18.0,<4)
 Requires-Dist: fits2image (>=0.4,<0.5)
 Requires-Dist: importlib-resources (>=6.4.5,<6.5.0)
 Requires-Dist: markdown (<4)

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/code/plugins.rst

@@ -10,6 +10,15 @@ functions, we support a range of optional plugin modules for the Toolkit.
 These range from adding the ability to interface with additional
 observatories and catalogs, to providing additional plotting or data analytics functionality.
 
+tom_across
+----------
+
+`tom_across <https://github.com/TOMToolkit/tom_across>`_
+
+This plugin integrates the Astrophysics Cross-Observatory Science Support (`ACROSS <https://science.data.nasa.gov/data-sites/across>_`)
+tools into the TOM Toolkit. Users can view observation records and target visibility directly from the target page using ACROSS's
+aggregated NASA mission observation and observatory status information.
+
 tom_hermes
 ----------
 

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/common/customsettings.rst

@@ -181,6 +181,9 @@ A list of observation facility classes to make available to your TOM. If
 you have written or downloaded a custom observation facility you would
 add the class to this list to make your TOM load it.
 
+INSTALLED_APPS that implement the ``observation_facilities()`` AppConfig integration
+point do not need to be listed here.
+
 `TOM_LATEX_PROCESSORS <#tom-latex-processors>`__
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

tomtoolkit-3.0.1/docs/customization/encrypted_model_fields.rst

@@ -0,0 +1,138 @@
+Encrypted Model Fields
+======================
+
+If your ``custom_code`` or reusable app needs to store a secret (e.g. an API key
+or password for an external service) — TOM Toolkit provides
+:class:`~tom_common.encryption.EncryptedModelField`, a model field that
+encrypts its value as it is stored in the database.
+
+.. note::
+
+   Encryption protects the secret from passive database exposure. It does
+   **not** protect it from anyone who can read your TOM's ``settings.SECRET_KEY``
+   (such as a server administrator). See :doc:`/deployment/encryption` for the
+   encryption documentation relevant to TOM administrators.
+
+This page describes how to add an encrypted field to a user-profile model,
+how to display it, and how to edit it. Working examples live in
+`tom_hermes <https://github.com/TOMToolkit/tom_hermes>`__,
+`tom_eso <https://github.com/TOMToolkit/tom_eso>`__, and
+`tom_demoapp <https://github.com/TOMToolkit/tom_demoapp>`__.
+
+Adding an EncryptedModelField
+-------------------------------
+
+Declare an :class:`~tom_common.encryption.EncryptedModelField` on your model:
+
+.. code-block:: python
+    :caption: models.py
+
+    from django.conf import settings
+    from django.db import models
+
+    from tom_common.encryption import EncryptedModelField
+
+
+    class MyAppProfile(models.Model):
+        user = models.OneToOneField(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
+        api_key = EncryptedModelField(null=True, blank=True)
+
+Read and write it like any other field; the value is encrypted on save and
+decrypted on load:
+
+.. code-block:: python
+
+    profile.api_key = 'something-secret'   # encrypted on save
+    profile.save()
+
+    profile.api_key                        # -> 'something-secret' (decrypted on load)
+
+Assigning ``None`` or ``''`` clears the stored value (the column becomes
+``NULL``); reading an unset value returns ``None``.
+
+Displaying the value of an encrypted field
+-------------------------------------------
+
+To show the value with a click-to-reveal control, use ``tom_common``'s
+``revealable_password_input.html`` partial. Pass it the **plaintext**, which
+comes from direct attribute access (``profile.api_key``):
+
+.. code-block:: python
+    :caption: e.g. an inclusion tag or a view's get_context_data
+
+    context = {'api_key': profile.api_key}  # plaintext becomes part of the template context
+
+.. code-block:: html+django
+    :caption: my_template.html
+
+    {% if api_key %}
+        {% include 'tom_common/partials/revealable_password_input.html' with value=api_key %}
+    {% else %}
+        (not set)
+    {% endif %}
+
+.. note::
+
+   Pass the plaintext only to templates the current user is allowed to see: the
+   partial embeds the plaintext value in the page HTML. Revealing it merely toggles
+   its visibility. Do **not** source the value from ``model_to_dict``, a DRF
+   serializer, or ``dumpdata`` — those return a ``REDACTED`` placeholder for
+   encrypted fields, never the secret. (If a profile card auto-iterates fields
+   with ``model_to_dict``, exclude the encrypted one and add ``profile.api_key``
+   back explicitly.)
+
+Editing the value in an UpdateView
+-----------------------------------
+
+List the field on a ``ModelForm``-based view. It renders as a masked input
+paired with a **Clear** checkbox:
+
+.. code-block:: python
+
+    class MyProfileUpdateView(UpdateView):
+        model = MyAppProfile
+        fields = ['api_key']
+
+On submitting the update form, an ``EncryptedModelField`` has the following behavior:
+
+- a new, typed-in value replaces the stored one;
+- a **blank** input keeps the stored value — so editing other fields on the
+  same form never wipes the secret;
+- Checking the **Clear** checkbox with a blank input removes the current value (column becomes ``NULL``);
+- a typed-in value together with **Clear** keeps the typed value (Clear is ignored).
+
+The form never renders the stored value, so it can't leak through the edit
+page. The placeholder text displayed in the input box signals the current state
+— ``(A stored value is hidden) — type to replace`` versus ``(not set) — type to add``.
+
+How it works (implementation details)
+-------------------------------------
+
+Each value is encrypted with a Fernet cipher derived from
+``settings.SECRET_KEY`` (via a key derivation function, :ref:`HKDF <kdf-implementation-details>`).
+Decryption also tries any ``settings.SECRET_KEY_FALLBACKS``, facilitating key rotation —
+see :doc:`/deployment/encryption` for the procedure and the ``rotate_encryption_key`` command.
+
+If a stored value cannot be decrypted under any active key, reading it raises
+``cryptography.fernet.InvalidToken`` — usually because a key was dropped from
+the rotation set before its data was re-encrypted.
+
+Limitations
+-----------
+
+- **No filtering.** Fernet ciphertext is non-deterministic, so equality lookups
+  can never match; ``MyAppProfile.objects.filter(api_key=...)`` raises
+  ``FieldError``. For a searchable secret, store a companion HMAC hash column
+  and query that.
+
+API reference
+-------------
+
+:class:`~tom_common.encryption.EncryptedModelField` (`source <https://github.com/TOMToolkit/tom_base/blob/dev/tom_common/encryption.py>`__)
+    A ``models.BinaryField`` subclass that encrypts on save and decrypts on
+    load. See the class docstring for the full method-level contract.
+
+:class:`~tom_common.encryption.EncryptedFormField` (`source <https://github.com/TOMToolkit/tom_base/blob/dev/tom_common/encryption.py>`__)
+    The form-side companion (masked input plus the blank-preserves-existing
+    behavior). ``ModelForm`` picks it up automatically via
+    :meth:`EncryptedModelField.formfield`.

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/data_services/create_dataservice.rst

@@ -188,6 +188,25 @@ This may also require you to create a ``build_headers`` method, or make use of t
 ``get_credentials`` methods. Saving the results to ``self.query_results`` could save time in other methods by not requiring
 you to redo the query.
 
+Configuration and Credentials
+=============================
+
+If your dataservice requires a configuration and/or credentials of any kind, retrieving these is built into the base
+DataService class. If possible, and using TOM-wide credentials, you should consider having TOM admins include the needed
+credentials as a nested dictionary inside the `DATA_SERVICES` attribute of ``settings.py`` named after the dataservice.
+These will be automatically retrieved by ``get_configuration``. If an API token is required, storing a key/value pair in
+the credentials named 'api_key' will allow ``get_credentials`` to automatically retrieve the token.
+
+.. code-block:: python
+    :caption: settings.py default credentials example
+
+    DATA_SERVICES = {
+        'MyService': {'user': 'Me', 'api_key': os.getenv('MyService_API_KEY', None)}
+    }
+
+In cases where more complex configurations or credentials are needed, consider overwriting or extending the
+``configuration``, ``get_configuration``, and/or ``get_credentials`` methods.
+
 ``DataService.query_targets``
 ++++++++++++++++++++++++++++++
 
@@ -264,6 +283,22 @@ into a model object with ``create_foo_from_query()``.
 Depending on the specifics of your data service, it may be reasonable to call the ``query_foo()`` methods independently,
 and/or part of ``query_targets``.
 
+Including Aliases:
+++++++++++++++++++
+Often when ingesting a new target from a dataservice, there will be multiple names or references for the target that you
+will want to include to avoid confusion and help with disambiguation within a TOM. This can be done in one of two ways:
+
+1. ``target_result``: Including an ``aliases`` key in any target results output by ``query_targets`` with a value that is
+a list of strings will automatically ingest those aliases as ``TargetNames``.
+
+2. ``query_aliases``: Sometimes, getting aliases can be more complex, possibly even requiring its own separate DB query. For
+These instances, you will need to include a ``query_aliases`` method that returns a list of strings, each string being a
+name for the target that is different from the primary name stored in ``Target.name``. See the
+:doc:`dataservices documentation <../api/tom_dataservices/data_services>` for more information.
+
+Note: By default a TOM's Match Filters apply to alias creation, so if an alias matches any existing name or alias already in the DB
+it will not be created.
+
 Querying Reduced Datums:
 ++++++++++++++++++++++++
 Data from a dataservice that needs to be stored as a ``ReducedDatum`` should be handled a little differently.
@@ -293,9 +328,10 @@ We will start by creating our query:
 ``DataService.create_reduced_datums_from_query``
 ================================================
 
-To create the ``ReducedDatum``s we will need a ``create_reduced_datums_from_query()`` method. This should take all of the data
-types and convert them into ``ReducedDatum`` objects. Be sure to use ``ReducedDatum.objects.get_or_create()`` to prevent
-re-creating existing objects.
+To create the ``ReducedDatum`` we will need a ``create_reduced_datums_from_query()`` method. This should take all of the data
+types and convert them into ``ReducedDatum`` objects. Be sure to use ``XXXXXReducedDatum.objects.get_or_create()`` to prevent
+re-creating existing objects where "XXXXX" represents the specific model you wish to use (such as Photometry, Spectroscopy, or Astrometry.)
+Details for the different types of data models can be found in the :doc:`API documentation <../api/tom_dataproducts/models>`.
 
 .. code-block:: python
     :caption: my_dataservice.MyDataService
@@ -318,19 +354,16 @@ re-creating existing objects.
                 # We might have some specific things we want to include based on type.
                 # For Photometry, for example, we need a magnitude, error, and filter to be displayed in the
                 # photometry plot on the target detail page.
-                datum_details['magnitude'] = datum['my_mag']
-                datum_details['error'] = datum['my_magerr']
-                datum_details['limit'] = datum['my_maglim']
-                datum_details['filter'] = datum['my_passband']
-
-            reduced_datum, __ = ReducedDatum.objects.get_or_create(
-                target=target,
-                timestamp=Time(datum['time'], format='iso', scale='utc').datetime,
-                data_type=data_type,
-                source_name=self.name,
-                value=datum_details
-            )
-            reduced_datums.append(reduced_datum)
+                reduced_datum, __ = PhotometryReducedDatum.objects.get_or_create(
+                    target=target,
+                    timestamp=Time(datum['time'], format='iso', scale='utc').datetime,
+                    source_name=self.name,
+                    brightness=datum['my_mag'],
+                    brightness_error=datum['my_magerr'],
+                    limit=datum['my_maglim'],
+                    bandpass=datum['my_passband']
+                )
+                reduced_datums.append(reduced_datum)
         return reduced_datums
 
 
@@ -357,16 +390,17 @@ exists, in several places where we want to update an existing target based on da
         :param target: A target object to be queried
         :return: query_parameters (usually a dict) that can be understood by `query_service()`
         """
-            if 'first' in target.name:
-                form_fields = {'first_field': target.name}
-                query_parameters = self.build_query_parameters(form_fields)
-            else:
-                query_parameters= {
-                    'ra_field': target.ra,
-                    'dec_field': target.dec,
-                    'radius': 0.5
-                    }
-            return query_parameters
+        # 2 examples for conditionally building query parameters
+        if 'first' in target.name:
+            form_fields = {'first_field': target.name}
+            query_parameters = self.build_query_parameters(form_fields)
+        else:
+            query_parameters= {
+                'ra_field': target.ra,
+                'dec_field': target.dec,
+                'radius': 0.5
+                }
+        return query_parameters
 
 
 Polishing Your Data Service:

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/deployment/encryption.rst

@@ -10,7 +10,7 @@ create an encrypted database field, your documentation is here:
 ------
 
 TOM Toolkit encrypts sensitive user data (API keys, observatory
-credentials, anything declared with :class:`EncryptedProperty`) using a
+credentials, anything declared with :class:`EncryptedModelField`) using a
 single Fernet cipher derived from Django's ``settings.SECRET_KEY``.
 That means when an encrypted field is written to or read from the database,
 a cipher is created. The cipher can encrypt unencrypted plaintext (in) and decrypt
@@ -89,7 +89,7 @@ The end-to-end procedure:
 
        python manage.py rotate_encryption_key
 
-   The command walks every :class:`EncryptedProperty` field across
+   The command walks every :class:`EncryptedModelField` field across
    ``INSTALLED_APPS``, decrypts each value (transparently using either
    the primary or a fallback), and re-encrypts under the primary. After
    this, no value in the database requires the fallback to decrypt.
@@ -116,7 +116,7 @@ What if ``SECRET_KEY`` is lost?
 
 If you lose ``SECRET_KEY`` and have no backup:
 
-- Every :class:`EncryptedProperty` value (saved API keys, observatory
+- Every :class:`EncryptedModelField` value (saved API keys, observatory
   credentials) becomes unrecoverable. The ciphertext is still in the
   database; the key needed to decrypt it is gone.
 - All Django signing-dependent states also break: outstanding password-reset
@@ -126,6 +126,34 @@ If you lose ``SECRET_KEY`` and have no backup:
 Treat ``SECRET_KEY`` backup with the same seriousness as your database
 backup.
 
+Backing up and moving encrypted data
+------------------------------------
+
+Because every encrypted value is tied to the ``SECRET_KEY`` that produced it,
+backing up and moving that data takes a little more care than ordinary rows.
+
+**Django fixtures do not carry encrypted values.** Django's ``dumpdata`` /
+``loaddata`` (its built-in way to export database rows to a file and load them
+back) cannot round-trip an encrypted field. By design, ``dumpdata`` writes the
+placeholder ``'******** (encrypted, not shown)'`` in place of each encrypted
+value — so secrets never end up in fixture files or version control — and
+``loaddata`` refuses to import that placeholder rather than store it as if it
+were the secret. (Plugin authors writing tests should likewise set encrypted
+values in code, not load them from a fixture.)
+
+To move encrypted data to another environment, use one of:
+
+- **A database-level copy** (e.g. ``pg_dump``). The stored ciphertext copies
+  over verbatim, but it only decrypts if the destination TOM uses the **same**
+  ``SECRET_KEY`` — or carries the source key in its ``SECRET_KEY_FALLBACKS`` —
+  since the Fernet key is derived from ``SECRET_KEY``.
+- **An application-level re-encrypt.** Run a one-off script that reads each
+  plaintext in the source (ordinary attribute access) and re-saves it in the
+  destination, which re-encrypts it under the destination's ``SECRET_KEY``. Use
+  this when the two environments have different keys.
+
+.. _kdf-implementation-details:
+
 Key Derivation Function Implementation Details
 ----------------------------------------------
 The derivation uses `HKDF <https://en.wikipedia.org/wiki/HKDF>`_

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/introduction/updating.rst

@@ -79,13 +79,28 @@ See the :ref:`Architecture Docs <ReducedDatum_label>` for a description, or
 :doc:`DataProducts API <../api/tom_dataproducts/models>` for a full code breakdown.
 
 We want to update all of your existing data to this new scheme where possible. This could take some time for large databases.
+Towards this end, we provide a `management command 
+<https://github.com/TOMToolkit/tom_base/blob/dev/tom_dataproducts/management/commands/migrate_reduced_datums.py>`_
+that will make "reasonable" assumptions about data values stored in ``ReducedDatum.value``. This command will search for
+commonly used brightness fields, filter fields, spectroscopy data, etc. and translate them into the new ``ReducedDatum``
+infrastructure. Anything unrecognized will remain in the catch-all ``value`` field. If you have highly customized fields
+stored for your datums, you should consider copying and editing the management command to suit your needs.
+
 
 .. Warning::
     This is a substantial DB change. Consider backing up your database before running this management command.
 
 ::
 
-   ./manage.py migrateReducedDatums
+   ./manage.py migrate_reduced_datums
+
+.. Note::
+    Data validation during this migration is partially dependent on your database infrastructure. 
+    You can test this migration by performing a dry run:
+
+    ::
+
+        ./manage.py migrate_reduced_datums --dry-run
 
 
 4.) Update ``settings.py``
@@ -107,12 +122,12 @@ with future changes. If you wish to use these settings, please make the followin
     ...
 
     # Replace your existing INSTALLED_APPS with the following:
-    INSTALLED_APPS = TOMTOOKIT_INSTALLED_APPS + [ 
+    INSTALLED_APPS = TOMTOOLKIT_INSTALLED_APPS + [ 
         'custom_code',  # Include any apps you have installed for your TOM that are not in default_settings
     ]
 
     # Replace your existing MIDDLEWARE with the following:
-    MIDDLEWARE = TOMTOOKIT_MIDDLEWARE + [
+    MIDDLEWARE = TOMTOOLKIT_MIDDLEWARE + [
         {{ custom_middleware }}  # Include any middleware you have installed for your TOM that are not in default_settings
     ]
 

tomtoolkit-3.0.1/docs/managing_data/accessing_data_through_REST_API.rst

@@ -0,0 +1,161 @@
+Accessing data through the REST API
+---------------------------------------
+
+`Django REST Framework (DRF) <https://www.django-rest-framework.org/>`_ is built into TOM Toolkit.
+This allows you to access the data in your TOM's database through a REST API.
+
+.. note::
+    If the ``DEFAULT_AUTHENTICATION_CLASSES`` key is not present in your
+    ``settings.REST_FRAMEWORK`` configuration dictionary, then you get
+    ``SessionAuthentication``, and ``BasicAuthentication`` because that's the DRF default.
+    To add ``TokenAuthentication``, your ``DEFAULT_AUTHENTICATION_CLASSES`` should look like this:
+
+    .. code:: python
+
+        REST_FRAMEWORK = {
+            'DEFAULT_AUTHENTICATION_CLASSES': [
+                'rest_framework.authentication.TokenAuthentication',
+                'rest_framework.authentication.SessionAuthentication',
+                'rest_framework.authentication.BasicAuthentication',
+            ],
+            # ... your existing REST_FRAMEWORK settings ...
+        }
+
+    - ``BasicAuthentication`` is used when you send username/password credentials in the ``AuthorizationHeader`` of an HTTP request.
+    - ``SessionAuthentication`` uses a cookie and CSRF protection to access the API from your TOM in a browser while logged in.
+    - ``TokenAuthentication`` uses your ``API Token`` available from the User Info of your User Profile of your TOM.
+
+    To see ``SessionAuthentication`` in action, while logged into your TOM, point your browser to the ``/api/`` endpoint.
+    This is the DRF API root. We'll show ``BasicAuthentication`` and ``TokenAuthentication`` in use below.
+
+
+Quick start: querying targets with curl
+#########################################
+
+The examples below query the targets endpoint on a TOM running locally at
+``http://127.0.0.1:8888`` with a user ``tom_user_1``. Adjust the host, port and
+username to match your deployment.
+
+Basic Authentication
+*************************************************
+
+.. code:: bash
+
+    curl -u tom_user_1  http://127.0.0.1:8888/api/targets/
+
+You'll be prompted for ``tom_user_1``'s password.
+You should receive a JSON blob with target data. Don't forget that trailing ``/``.
+
+This is ``BasicAuthentication``: ``curl`` sends the username and password in the
+``AuthenticationHeader`` of the HTTP request. 
+
+Token Authentication
+*************************************************
+
+Every user has a personal API token, shown as **API Token** on their
+**User Profile** page. A token suits scripts and cron jobs because it
+needs no interactive prompt. Secure your API token as you would a password.
+
+Rather than pass in a username and be prompted for a password, we'll authenticate
+by sending the token in an ``Authorization`` header:
+
+To keep the API token out of your command history and scripts, export it as an
+environment variable once and reference it in the header:
+
+.. code:: bash
+
+    export TOM_API_TOKEN="API-token-copied-from-User-Profile"
+    curl -H "Authorization: Token $TOM_API_TOKEN" http://127.0.0.1:8888/api/targets/
+
+
+Next Step: querying targets in code
+#########################################
+
+The same requests work from Python with the
+`requests <https://requests.readthedocs.io/>`_ library.
+
+Basic Authentication
+*************************************************
+
+Pass your username and password as the ``auth`` tuple:
+
+.. code:: python
+
+    import requests
+
+    response = requests.get(
+        'http://127.0.0.1:8888/api/targets/',
+        auth=('tom_user_1', 'your-password'),
+    )
+    targets = response.json()
+
+``targets`` now holds the same JSON you got back from ``curl``.
+
+Token Authentication
+*************************************************
+
+Send your API token in an ``Authorization`` header instead. The API token
+substitutes for the `BasicAuthentication` username and  password.
+
+.. code:: python
+
+    import requests
+
+    headers = {'Authorization': 'Token API-token-copied-from-User-Profile'}
+    response = requests.get('http://127.0.0.1:8888/api/targets/', headers=headers)
+    print('status:', response.status_code)
+    print('targets:  ', response.json())
+
+Don't hard-code real credentials: read the password or token from an environment
+variable (e.g. ``os.environ['TOM_API_TOKEN']``) as in the ``curl`` example above.
+
+Obtaining your API Token programmatically
+#########################################
+
+Above, we've seen how to access your TOM's data using ``curl`` and ``Python``,
+via ``BasicAuthentication`` (username, password) and ``TokenAuthentication`` (API Token).
+
+Your API Token is available from the User Info card of your User Profile. (You may rotate
+your API Token from the User Profile update page (available from the pencil (edit) icon of
+the User Info card). Rotating your API token is analogous to, but separate from, changing
+your password).
+
+Here we show how to obtain your API Token programmatically. Django REST Framework
+provides the mechanism for this and it is available at a the ``api/token-auth`` endpoint.
+
+Using curl
+******************************************
+
+Using the same assumptions as above with respect to ``host``, ``port``, ``username``,
+and ``password``:
+
+.. code:: bash
+
+    curl --request POST http://127.0.0.1:8888/api/token-auth/ \
+         --header "Content-Type: application/json" \
+         --data '{"username": "tom_user_1", "password": "your-password"}'
+
+Things to note here:
+ - This is a ``POST`` request.
+ - The ``Content-Type`` specified in the request header lets DRF know to expect a JSON payload.
+ - The ``BasicAuthentication`` credentials are passed as the JSON payload of the request.
+
+The ouput you see will be JSON to stdout of the form ``{"token":"3bc76a8b6400182d617e9a1ce75dfa92d87412a0"}``.
+
+Using Python
+******************************************
+Here is the equivalent request made from Python code:
+
+.. code:: python
+
+    import requests
+
+    response = requests.post(
+        'http://127.0.0.1:8888/api/token-auth/',
+        json={'username': 'tom_user_1', 'password': 'your-password'},
+    )
+    print('status:', response.status_code)
+    print('json:  ', response.json())  # {"token":"3bc76a8b6400182d617e9a1ce75dfa92d87412a0"}
+
+
+Further details can be found in the `DRF Authentication API Guide <https://www.django-rest-framework.org/api-guide/authentication/>`_.

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/managing_data/index.rst

@@ -11,6 +11,7 @@ Managing Data
   Continuous data sharing <continuous_sharing>
   Streaming data <stream_pub_sub>
   Single-target data service <single_target_data_service>
+  Accessing data through the REST API <accessing_data_through_REST_API>
   Visualizing data <plotting_data>
 
 The TOM's Data Models

{tomtoolkit-3.0.0a12 → tomtoolkit-3.0.1}/docs/managing_data/tom_direct_sharing.rst

@@ -61,6 +61,9 @@ When your TOM receives a new ``Target`` from another TOM it will be saved to you
 or alias doesn't match that of a target that already exists in the database, a new target will be created and added to a
 new ``TargetList`` called "Imported from <TOM Name>".
 
+Targets shared from a TOM with a custom ``Target`` model that has unique model fields will fill out any identically
+named fields in your ``Target`` model and the remaining fields will be ingested as ``TargetExtras``.
+
 Target Lists:
 -------------
 When your TOM receives a new ``TargetList`` from another TOM it will be saved to your TOM's database. If the targets in