tomtoolkit 3.0.0a13__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.0a13 → tomtoolkit-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tomtoolkit
-Version: 3.0.0a13
+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.0a13 → 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.0a13 → 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.0a13 → 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.0a13 → 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.0a13 → 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.0a13 → 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

{tomtoolkit-3.0.0a13 → tomtoolkit-3.0.1}/docs/observing/observation_module.rst

@@ -105,6 +105,32 @@ like this:
 This means our new observation facility module has been successfully
 loaded.
 
+Adding a facility from an app
+-----------------------------
+
+A facility implemented as a Django reusable app can advertise itself
+to a TOM without requiring an admin to include it in ``settings.TOM_FACILITY_CLASSES``,
+which simplifies its installation.
+To do this, implement the ``observation_facilities()`` integration point
+on the app's ``AppConfig`` subclass:
+
+.. code:: python
+
+   class MyAppConfig(AppConfig):
+       name = 'myapp'
+
+       def observation_facilities(self):
+           return [{'class': f'{self.name}.myfacility.MyObservationFacility'}]
+
+More details can be found on the ``tom_demoapp`` repository `wiki <https://github.com/TOMToolkit/tom_demoapp/wiki/Integration-Points#observation-facilities>`_.
+
+Facilities from both ``settings.TOM_FACILITY_CLASSES`` and the apps implementing
+the integration point have the same behavior with respect to target detail page buttons
+and Facilties navbar menu items.
+So, if your facility implements the ``observation_facilities()`` integration point,
+adding the app to ``INSTALLED_APPS`` is all that is required for installation.
+See ``tom_demoapp`` for a demonstration of the basics  and ``tom_cfht`` for a fully worked example.
+
 BaseRoboticObservationFacility and BaseRoboticObservationForm
 -------------------------------------------------------------
 
@@ -126,6 +152,58 @@ use. The ``BaseRoboticObservationForm`` class, just like the previous
 super class, contains logic and layout that all observation facility
 form classes should contain.
 
+Linking to a facility detail page
+---------------------------------
+TOMToolkit typically interacts with observation facilities to submit requests to observe
+a specific target. Observation request forms are typically accessed via buttons on the Observe
+tab of the target detail page for the target being observed. When a TOM needs to interact with
+an observation facility for reasons that are not target specific, a "facility detail" page can
+be specified. For example, the Canada France Hawaii telescope (CFHT) facility detail page allows
+a TOM to sync target data with the CFHT P2 tool. This precludes having to visit every target's
+detail page to sync its data. The faciliity class attribute ``detail_url_name``
+supplies the URL of its facility detail page.
+
+A facility may set ``detail_url_name`` to the namespaced Django URL name of a page
+that presents general, non-target-specific funcionality. Facilities that set it
+appear in the navbar **Facilities** dropdown, linked to that page:
+
+.. code:: python
+
+   class MyObservationFacility(BaseRoboticObservationFacility):
+       name = 'MyFacility'
+       detail_url_name = 'myapp:facility-detail'
+
+``detail_url_name`` is optional and is omitted from the minimal example above. A facility
+that leaves it unset is still fully registered -- it has an observe button and observation
+forms -- but gets no menu item in the Facilities navbar dropdown. If no facility sets it,
+the dropdown is not displayed.
+See ``tom_demoapp`` for a demonstration of the basics, including deriving the namespace from the
+AppConfig's ``name`` and ``tom_cfht`` for a fully worked example.
+
+For ``detail_url_name`` to resolve, the app's URLs must be mounted in the TOM under that
+namespace. A reusable app mounts its own ``urls.py`` through the ``include_url_paths()``
+AppConfig integration point -- ``tom_common`` collects these paths from every installed
+app, so no TOM ``urls.py`` edits are required:
+
+.. code:: python
+
+   class MyAppConfig(AppConfig):
+       name = 'myapp'
+       route_prefix = 'myapp'  # prefixes every route in myapp's urls.py: HOST/myapp/...
+
+       def include_url_paths(self):
+           return [
+               path(f'{self.route_prefix}/', include(f'{self.name}.urls')),
+           ]
+
+(``route_prefix`` is a TOM plugin convention, not a Django AppConfig attribute.) The
+included ``urls.py`` supplies the namespace by declaring ``app_name`` -- by convention
+derived from the AppConfig (``app_name = MyAppConfig.name``) so the namespace and the
+package name can never disagree -- and must contain a ``path()`` whose ``name=`` is the
+second half of ``detail_url_name``. If ``app_name`` is missing, the app's URL names are
+un-namespaced and ``detail_url_name`` will not reverse; the menu item is skipped with a
+logged warning.
+
 Implementing observation submission
 -----------------------------------