splent-feature-github 0.1.0__tar.gz → 0.2.0__tar.gz

splent_feature_github-0.2.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: splent_feature_github
+Version: 0.2.0
+License-Expression: LGPL-3.0-or-later
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: COPYING
+License-File: COPYING.LESSER
+Dynamic: license-file
+
+# splent_feature_github
+
+The `github` feature of a [SPLENT](https://splent.io) product line.
+
+Sign in and sign up with GitHub, and connect a GitHub account to an account
+from its profile. identities runs the sign-in for every provider, and this
+feature describes GitHub to it: its endpoints, its scope (`GITHUB_SCOPE`),
+and how to read who signed in from its API, the verified address included.
+A new account takes an address GitHub verified (from `/user/emails`, the
+primary one first, never the public one on `/user`) and the name it gives,
+and the person adds the surname before it is opened. A GitHub account
+always signs in to the account it is linked to, and never to an existing
+account because the email matches. It needs `auth`, `profile` and
+`identities`, which keeps the linked accounts.
+
+A SPLENT feature is a Python package that a product composes with others.
+Its models, routes, services, templates and hooks are registered when the
+product starts. What this feature provides and requires is listed in the
+`[tool.splent.contract]` section of `pyproject.toml`, which
+`splent feature:contract --write` keeps in sync with the source.
+
+## Settings
+
+| Setting | Default | What it is |
+|---|---|---|
+| `GITHUB_CLIENT_ID` | empty | The client id of the OAuth app registered at https://github.com/settings/developers |
+| `GITHUB_CLIENT_SECRET` | empty | Its secret |
+| `GITHUB_SCOPE` | `user:email` | What the sign-in asks GitHub for. `user:email` lets `/user/emails` say which addresses GitHub verified; without it every new account asks for an address, which then has to be confirmed by mail |
+
+Without both, GitHub sign-in is off: the app logs a warning at start, and
+whoever tries is told it is not available. The callback registered with
+GitHub is `<OAUTH_REDIRECT_BASE_URL>/github/authorize` (identities' setting).
+
+## Where it shows
+
+It fills the slots other features open, by name, so it composes with
+whatever the product has and overrides nothing.
+
+| Slot | Opened by | What GitHub draws |
+|---|---|---|
+| `auth.login.providers` | auth | The GitHub button, under "or continue with" |
+| `signup.providers` | signup, when the product has it | The same button, after the sign-up form |
+| `profile.edit.sections` | profile | The linked account, as a link to it on GitHub, with a disconnect button, or a "Connect GitHub" link |
+| `layout.head.css` | the product's app shell | Its stylesheet, `assets/css/github.css` |
+
+It takes order 10 in the first three, before ORCID's 20. The button carries
+where the reader was heading (`?next=`), and only a path on this site. The
+disconnect button opens identities' modal.
+
+GitHub's dark grey is in `assets/css/github.css`, never on the elements. The
+public shell loads the file from the asset registry (`register_asset`), and
+the app shell, which does not render the registry, through
+`layout.head.css`. A product that wants another look overrides
+`.btn.btn-github` and the `github-identity__*` classes in a stylesheet of its
+own.
+
+## A product without signup
+
+A product that does not install `splent_feature_signup` is closed, and its
+accounts are opened by an administrator. GitHub follows the rule identities
+holds for every provider.
+
+| Visitor | With signup | Without signup |
+|---|---|---|
+| Signs in with a GitHub account already linked | Signed in | Signed in |
+| Connects GitHub from their profile | Linked | Linked |
+| Signs in with a GitHub account linked to nobody | Asked for the details of a new account, which opens at once with GitHub's verified address, or, when GitHub verified none and the person typed one, once the person follows the link mailed to it and signs in with GitHub again, if the product confirms addresses | Sent back to the login page with a translated message that asks them to request access from an administrator, or to connect GitHub from their profile if they have an account |
+
+## The github table
+
+Earlier versions kept every linked GitHub account twice: in
+`external_identity`, which signs people in, and in a `github` table keyed by
+profile, which only `get_github()` read and nothing called.
+`github0002_into_ext_identity` folds the table into `external_identity` and
+drops it, and `get_github()` goes with it. Each row becomes the account's
+GitHub identity (its numeric id as text, its login as the username), or
+completes the one it already has. A row that would lose a link or give it to
+another account stops the migration before anything changes, and the
+message names the rows. The downgrade puts the table back with a row for
+every GitHub identity of an account with a profile.
+
+## Translations
+
+The edit-profile row and the messages about GitHub's answers ship with a
+Spanish catalog.
+
+## Use it in a product
+
+```bash
+splent feature:add splent_feature_github
+```
+
+## Develop
+
+The tests simulate GitHub (`tests/conftest.py`): the flow's OAuth client
+answers the token exchange, `/user` and `/user/emails` as each test chooses.
+
+```bash
+splent feature:test splent_feature_github --with identities --with orcid
+splent feature:contract splent_feature_github
+```
+
+## Release
+
+```bash
+splent feature:release splent_feature_github --dry-run --bump patch
+splent feature:release splent_feature_github
+```
+
+The first command rehearses the release and changes nothing. The second
+publishes it to the git forge and to PyPI, and a PyPI version is permanent.
+This version needs the identities that brings the shared flow and
+`provider_email_verified`, so the two are released together.

splent_feature_github-0.2.0/README.md

@@ -0,0 +1,113 @@
+# splent_feature_github
+
+The `github` feature of a [SPLENT](https://splent.io) product line.
+
+Sign in and sign up with GitHub, and connect a GitHub account to an account
+from its profile. identities runs the sign-in for every provider, and this
+feature describes GitHub to it: its endpoints, its scope (`GITHUB_SCOPE`),
+and how to read who signed in from its API, the verified address included.
+A new account takes an address GitHub verified (from `/user/emails`, the
+primary one first, never the public one on `/user`) and the name it gives,
+and the person adds the surname before it is opened. A GitHub account
+always signs in to the account it is linked to, and never to an existing
+account because the email matches. It needs `auth`, `profile` and
+`identities`, which keeps the linked accounts.
+
+A SPLENT feature is a Python package that a product composes with others.
+Its models, routes, services, templates and hooks are registered when the
+product starts. What this feature provides and requires is listed in the
+`[tool.splent.contract]` section of `pyproject.toml`, which
+`splent feature:contract --write` keeps in sync with the source.
+
+## Settings
+
+| Setting | Default | What it is |
+|---|---|---|
+| `GITHUB_CLIENT_ID` | empty | The client id of the OAuth app registered at https://github.com/settings/developers |
+| `GITHUB_CLIENT_SECRET` | empty | Its secret |
+| `GITHUB_SCOPE` | `user:email` | What the sign-in asks GitHub for. `user:email` lets `/user/emails` say which addresses GitHub verified; without it every new account asks for an address, which then has to be confirmed by mail |
+
+Without both, GitHub sign-in is off: the app logs a warning at start, and
+whoever tries is told it is not available. The callback registered with
+GitHub is `<OAUTH_REDIRECT_BASE_URL>/github/authorize` (identities' setting).
+
+## Where it shows
+
+It fills the slots other features open, by name, so it composes with
+whatever the product has and overrides nothing.
+
+| Slot | Opened by | What GitHub draws |
+|---|---|---|
+| `auth.login.providers` | auth | The GitHub button, under "or continue with" |
+| `signup.providers` | signup, when the product has it | The same button, after the sign-up form |
+| `profile.edit.sections` | profile | The linked account, as a link to it on GitHub, with a disconnect button, or a "Connect GitHub" link |
+| `layout.head.css` | the product's app shell | Its stylesheet, `assets/css/github.css` |
+
+It takes order 10 in the first three, before ORCID's 20. The button carries
+where the reader was heading (`?next=`), and only a path on this site. The
+disconnect button opens identities' modal.
+
+GitHub's dark grey is in `assets/css/github.css`, never on the elements. The
+public shell loads the file from the asset registry (`register_asset`), and
+the app shell, which does not render the registry, through
+`layout.head.css`. A product that wants another look overrides
+`.btn.btn-github` and the `github-identity__*` classes in a stylesheet of its
+own.
+
+## A product without signup
+
+A product that does not install `splent_feature_signup` is closed, and its
+accounts are opened by an administrator. GitHub follows the rule identities
+holds for every provider.
+
+| Visitor | With signup | Without signup |
+|---|---|---|
+| Signs in with a GitHub account already linked | Signed in | Signed in |
+| Connects GitHub from their profile | Linked | Linked |
+| Signs in with a GitHub account linked to nobody | Asked for the details of a new account, which opens at once with GitHub's verified address, or, when GitHub verified none and the person typed one, once the person follows the link mailed to it and signs in with GitHub again, if the product confirms addresses | Sent back to the login page with a translated message that asks them to request access from an administrator, or to connect GitHub from their profile if they have an account |
+
+## The github table
+
+Earlier versions kept every linked GitHub account twice: in
+`external_identity`, which signs people in, and in a `github` table keyed by
+profile, which only `get_github()` read and nothing called.
+`github0002_into_ext_identity` folds the table into `external_identity` and
+drops it, and `get_github()` goes with it. Each row becomes the account's
+GitHub identity (its numeric id as text, its login as the username), or
+completes the one it already has. A row that would lose a link or give it to
+another account stops the migration before anything changes, and the
+message names the rows. The downgrade puts the table back with a row for
+every GitHub identity of an account with a profile.
+
+## Translations
+
+The edit-profile row and the messages about GitHub's answers ship with a
+Spanish catalog.
+
+## Use it in a product
+
+```bash
+splent feature:add splent_feature_github
+```
+
+## Develop
+
+The tests simulate GitHub (`tests/conftest.py`): the flow's OAuth client
+answers the token exchange, `/user` and `/user/emails` as each test chooses.
+
+```bash
+splent feature:test splent_feature_github --with identities --with orcid
+splent feature:contract splent_feature_github
+```
+
+## Release
+
+```bash
+splent feature:release splent_feature_github --dry-run --bump patch
+splent feature:release splent_feature_github
+```
+
+The first command rehearses the release and changes nothing. The second
+publishes it to the git forge and to PyPI, and a PyPI version is permanent.
+This version needs the identities that brings the shared flow and
+`provider_email_verified`, so the two are released together.

{splent_feature_github-0.1.0 → splent_feature_github-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_feature_github"
-version = "0.1.0"
+version = "0.2.0"
 readme = "README.md"
 requires-python = ">=3.13"
 license = "LGPL-3.0-or-later"
@@ -34,29 +34,30 @@ cli_version = "1.25.1"
 # registration time, which have no literal path to find in source).
 [tool.splent.contract]
 description = "Sign in and sign up with GitHub, and connect a GitHub account to an account from its profile"
-archetype = "full"
+archetype = "light"
 
 [tool.splent.contract.provides]
 routes     = ["/account/connect/github", "/github/authorize", "/github/login"]
 blueprints = ["github_bp"]
-models     = ["Github"]
+models     = []
 commands   = []
 hooks      = ["auth.login.providers", "layout.head.css", "profile.edit.sections", "signup.providers"]
-services   = ["GithubService"]
+services   = []
 signals    = []
 translations = ["es"]
 docker     = []
 
 [tool.splent.contract.requires]
 features = ["auth", "identities", "profile"]
+features_manual = ["profile"]
 features_optional = ["signup"]
-env_vars = ["GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET"]
-signals  = ["identity-disconnected"]
+env_vars = ["GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET", "GITHUB_SCOPE"]
+signals  = []
 
 [tool.splent.contract.extensible]
-services  = ["GithubService"]
+services  = []
 templates = ["hooks/github_login_button.html", "hooks/github_profile_row.html"]
-models    = ["Github"]
+models    = []
 hooks     = ["auth.login.providers", "layout.head.css", "profile.edit.sections", "signup.providers"]
 routes    = true
 
@@ -76,7 +77,11 @@ routes    = true
 # product's port offset, so two products can run at once.
 [tool.splent.config]
 # The OAuth app registered at https://github.com/settings/developers.
-# Without both values GitHub sign-in fails with a message and the app logs a
-# warning.
+# Without both values GitHub sign-in is off: the app logs a warning at start,
+# and whoever tries is told it is not available.
 GITHUB_CLIENT_ID = ""
 GITHUB_CLIENT_SECRET = ""
+# What the sign-in asks GitHub for. user:email lets GitHub say which of the
+# person's addresses it verified; without it every new account asks for an
+# address, which then has to be confirmed by mail.
+GITHUB_SCOPE = "user:email"

splent_feature_github-0.2.0/src/splent_feature_github.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: splent_feature_github
+Version: 0.2.0
+License-Expression: LGPL-3.0-or-later
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: COPYING
+License-File: COPYING.LESSER
+Dynamic: license-file
+
+# splent_feature_github
+
+The `github` feature of a [SPLENT](https://splent.io) product line.
+
+Sign in and sign up with GitHub, and connect a GitHub account to an account
+from its profile. identities runs the sign-in for every provider, and this
+feature describes GitHub to it: its endpoints, its scope (`GITHUB_SCOPE`),
+and how to read who signed in from its API, the verified address included.
+A new account takes an address GitHub verified (from `/user/emails`, the
+primary one first, never the public one on `/user`) and the name it gives,
+and the person adds the surname before it is opened. A GitHub account
+always signs in to the account it is linked to, and never to an existing
+account because the email matches. It needs `auth`, `profile` and
+`identities`, which keeps the linked accounts.
+
+A SPLENT feature is a Python package that a product composes with others.
+Its models, routes, services, templates and hooks are registered when the
+product starts. What this feature provides and requires is listed in the
+`[tool.splent.contract]` section of `pyproject.toml`, which
+`splent feature:contract --write` keeps in sync with the source.
+
+## Settings
+
+| Setting | Default | What it is |
+|---|---|---|
+| `GITHUB_CLIENT_ID` | empty | The client id of the OAuth app registered at https://github.com/settings/developers |
+| `GITHUB_CLIENT_SECRET` | empty | Its secret |
+| `GITHUB_SCOPE` | `user:email` | What the sign-in asks GitHub for. `user:email` lets `/user/emails` say which addresses GitHub verified; without it every new account asks for an address, which then has to be confirmed by mail |
+
+Without both, GitHub sign-in is off: the app logs a warning at start, and
+whoever tries is told it is not available. The callback registered with
+GitHub is `<OAUTH_REDIRECT_BASE_URL>/github/authorize` (identities' setting).
+
+## Where it shows
+
+It fills the slots other features open, by name, so it composes with
+whatever the product has and overrides nothing.
+
+| Slot | Opened by | What GitHub draws |
+|---|---|---|
+| `auth.login.providers` | auth | The GitHub button, under "or continue with" |
+| `signup.providers` | signup, when the product has it | The same button, after the sign-up form |
+| `profile.edit.sections` | profile | The linked account, as a link to it on GitHub, with a disconnect button, or a "Connect GitHub" link |
+| `layout.head.css` | the product's app shell | Its stylesheet, `assets/css/github.css` |
+
+It takes order 10 in the first three, before ORCID's 20. The button carries
+where the reader was heading (`?next=`), and only a path on this site. The
+disconnect button opens identities' modal.
+
+GitHub's dark grey is in `assets/css/github.css`, never on the elements. The
+public shell loads the file from the asset registry (`register_asset`), and
+the app shell, which does not render the registry, through
+`layout.head.css`. A product that wants another look overrides
+`.btn.btn-github` and the `github-identity__*` classes in a stylesheet of its
+own.
+
+## A product without signup
+
+A product that does not install `splent_feature_signup` is closed, and its
+accounts are opened by an administrator. GitHub follows the rule identities
+holds for every provider.
+
+| Visitor | With signup | Without signup |
+|---|---|---|
+| Signs in with a GitHub account already linked | Signed in | Signed in |
+| Connects GitHub from their profile | Linked | Linked |
+| Signs in with a GitHub account linked to nobody | Asked for the details of a new account, which opens at once with GitHub's verified address, or, when GitHub verified none and the person typed one, once the person follows the link mailed to it and signs in with GitHub again, if the product confirms addresses | Sent back to the login page with a translated message that asks them to request access from an administrator, or to connect GitHub from their profile if they have an account |
+
+## The github table
+
+Earlier versions kept every linked GitHub account twice: in
+`external_identity`, which signs people in, and in a `github` table keyed by
+profile, which only `get_github()` read and nothing called.
+`github0002_into_ext_identity` folds the table into `external_identity` and
+drops it, and `get_github()` goes with it. Each row becomes the account's
+GitHub identity (its numeric id as text, its login as the username), or
+completes the one it already has. A row that would lose a link or give it to
+another account stops the migration before anything changes, and the
+message names the rows. The downgrade puts the table back with a row for
+every GitHub identity of an account with a profile.
+
+## Translations
+
+The edit-profile row and the messages about GitHub's answers ship with a
+Spanish catalog.
+
+## Use it in a product
+
+```bash
+splent feature:add splent_feature_github
+```
+
+## Develop
+
+The tests simulate GitHub (`tests/conftest.py`): the flow's OAuth client
+answers the token exchange, `/user` and `/user/emails` as each test chooses.
+
+```bash
+splent feature:test splent_feature_github --with identities --with orcid
+splent feature:contract splent_feature_github
+```
+
+## Release
+
+```bash
+splent feature:release splent_feature_github --dry-run --bump patch
+splent feature:release splent_feature_github
+```
+
+The first command rehearses the release and changes nothing. The second
+publishes it to the git forge and to PyPI, and a PyPI version is permanent.
+This version needs the identities that brings the shared flow and
+`provider_email_verified`, so the two are released together.

{splent_feature_github-0.1.0 → splent_feature_github-0.2.0}/src/splent_feature_github.egg-info/SOURCES.txt

@@ -11,15 +11,14 @@ src/splent_io/splent_feature_github/__init__.py
 src/splent_io/splent_feature_github/config.py
 src/splent_io/splent_feature_github/hooks.py
 src/splent_io/splent_feature_github/models.py
-src/splent_io/splent_feature_github/repositories.py
 src/splent_io/splent_feature_github/routes.py
 src/splent_io/splent_feature_github/services.py
-src/splent_io/splent_feature_github/signals.py
 src/splent_io/splent_feature_github/assets/css/github.css
 src/splent_io/splent_feature_github/migrations/alembic.ini
 src/splent_io/splent_feature_github/migrations/env.py
 src/splent_io/splent_feature_github/migrations/script.py.mako
 src/splent_io/splent_feature_github/migrations/versions/7ace6050fb3f_splent_feature_github.py
+src/splent_io/splent_feature_github/migrations/versions/github0002_into_ext_identity.py
 src/splent_io/splent_feature_github/templates/hooks/github_login_button.html
 src/splent_io/splent_feature_github/templates/hooks/github_profile_row.html
 src/splent_io/splent_feature_github/translations/es/LC_MESSAGES/messages.mo

{splent_feature_github-0.1.0 → splent_feature_github-0.2.0}/src/splent_io/splent_feature_github/__init__.py

@@ -1,13 +1,7 @@
 from splent_framework.assets.asset_registry import register_asset
 from splent_framework.blueprints.base_blueprint import create_blueprint
-from splent_framework.refinement import refine_model
-from splent_framework.services.service_locator import register_service
 
-from splent_io.splent_feature_github.models import UserProfileGithubMixin
-from splent_io.splent_feature_github.services import (
-    GithubService,
-    register_github_client,
-)
+from splent_io.splent_feature_github.services import register_github
 
 github_bp = create_blueprint(__name__)
 
@@ -16,9 +10,9 @@ def init_feature(app):
     from splent_io.splent_feature_github.config import inject_config
 
     inject_config(app)
-    register_service(app, "GithubService", GithubService)
-    register_github_client(app)
-    refine_model("UserProfile", UserProfileGithubMixin)
+    # GitHub on identities' registry: identities runs the sign-in, the
+    # callback, the connect and the opening of new accounts.
+    register_github(app)
     # GitHub's colours on its button and its profile row, for the public
     # shell. The app shell gets the same file through layout.head.css.
     register_asset(

{splent_feature_github-0.1.0 → splent_feature_github-0.2.0}/src/splent_io/splent_feature_github/config.py

@@ -2,17 +2,20 @@
 github feature configuration.
 
 The OAuth app registered at https://github.com/settings/developers.
-Without both values GitHub sign-in is disabled (the redirect fails and the
-user is sent back to the login page with a message).
+Without both values GitHub sign-in is off: the app logs a warning at start,
+and whoever tries is told it is not available.
 """
 
 import os
 
+from splent_io.splent_feature_github.services import DEFAULT_SCOPE
+
 
 def inject_config(app):
     app.config.update(
         {
             "GITHUB_CLIENT_ID": os.getenv("GITHUB_CLIENT_ID", ""),
             "GITHUB_CLIENT_SECRET": os.getenv("GITHUB_CLIENT_SECRET", ""),
+            "GITHUB_SCOPE": os.getenv("GITHUB_SCOPE", "").strip() or DEFAULT_SCOPE,
         }
     )

{splent_feature_github-0.1.0 → splent_feature_github-0.2.0}/src/splent_io/splent_feature_github/hooks.py

@@ -2,9 +2,9 @@
 
 GitHub offers itself first on the login page (auth's auth.login.providers)
 and on the sign-up page when the product has one (signup's
-signup.providers). On the edit-profile page it shows the linked account, or
-a "Connect GitHub" link, first among the sections below the form
-(profile's profile.edit.sections).
+signup.providers). On the edit-profile page it shows the linked account, as a
+link to it on GitHub, or a "Connect GitHub" link, first among the sections
+below the form (profile's profile.edit.sections).
 
 Every slot is filled by name, so a product without signup simply has no
 sign-up page to show the button on.
@@ -34,17 +34,15 @@ def github_login_button():
 
 
 def github_profile_row():
+    from splent_io.splent_feature_github.services import PROVIDER, github_url
     from splent_io.splent_feature_identities.services import IdentitiesService
 
-    identity = next(
-        (
-            i
-            for i in IdentitiesService().identities_of(current_user.id)
-            if i.provider == "github"
-        ),
-        None,
+    identity = IdentitiesService().identity_of(current_user.id, PROVIDER)
+    return render_template(
+        "hooks/github_profile_row.html",
+        identity=identity,
+        github_url=github_url(identity) if identity else None,
     )
-    return render_template("hooks/github_profile_row.html", identity=identity)
 
 
 def github_stylesheet():