sg-mockgun 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. sg_mockgun-0.1.0/.github/workflows/release.yml +61 -0
  2. sg_mockgun-0.1.0/.gitignore +5 -0
  3. sg_mockgun-0.1.0/LICENSE +55 -0
  4. sg_mockgun-0.1.0/PKG-INFO +173 -0
  5. sg_mockgun-0.1.0/README.md +109 -0
  6. sg_mockgun-0.1.0/docs/api3-probe-2026-11-12.md +119 -0
  7. sg_mockgun-0.1.0/pyproject.toml +21 -0
  8. sg_mockgun-0.1.0/src/sg_mockgun/__init__.py +35 -0
  9. sg_mockgun-0.1.0/src/sg_mockgun/clean.py +59 -0
  10. sg_mockgun-0.1.0/src/sg_mockgun/errors.py +42 -0
  11. sg_mockgun-0.1.0/src/sg_mockgun/events.py +141 -0
  12. sg_mockgun-0.1.0/src/sg_mockgun/fields.py +93 -0
  13. sg_mockgun-0.1.0/src/sg_mockgun/mockgun.py +1107 -0
  14. sg_mockgun-0.1.0/src/sg_mockgun/schema.py +120 -0
  15. sg_mockgun-0.1.0/src/sg_mockgun/schemas/__init__.py +11 -0
  16. sg_mockgun-0.1.0/src/sg_mockgun/schemas/fpt_8_91/schema.pickle +0 -0
  17. sg_mockgun-0.1.0/src/sg_mockgun/schemas/fpt_8_91/schema_entity.pickle +0 -0
  18. sg_mockgun-0.1.0/src/sg_mockgun/schemas/upstream_3_10_5/schema.pickle +98684 -0
  19. sg_mockgun-0.1.0/src/sg_mockgun/schemas/upstream_3_10_5/schema_entity.pickle +1003 -0
  20. sg_mockgun-0.1.0/src/sg_mockgun/server.py +263 -0
  21. sg_mockgun-0.1.0/src/sg_mockgun/wire.py +104 -0
  22. sg_mockgun-0.1.0/tests/fixtures/upstream/schema.pickle +98684 -0
  23. sg_mockgun-0.1.0/tests/fixtures/upstream/schema_entity.pickle +1003 -0
  24. sg_mockgun-0.1.0/tests/test_bundled_schema.py +34 -0
  25. sg_mockgun-0.1.0/tests/test_clean.py +77 -0
  26. sg_mockgun-0.1.0/tests/test_event_log.py +125 -0
  27. sg_mockgun-0.1.0/tests/test_fields.py +29 -0
  28. sg_mockgun-0.1.0/tests/test_rest_revive.py +152 -0
  29. sg_mockgun-0.1.0/tests/test_schema_writes.py +120 -0
  30. sg_mockgun-0.1.0/tests/test_server.py +106 -0
  31. sg_mockgun-0.1.0/tests/test_upstream_mockgun.py +759 -0
  32. sg_mockgun-0.1.0/tests/test_wire.py +44 -0
  33. sg_mockgun-0.1.0/tools/pull_schema.py +58 -0
  34. sg_mockgun-0.1.0/uv.lock +246 -0
@@ -0,0 +1,61 @@
1
+ # Publish to PyPI when a GitHub release is published. Nothing else triggers it: a tag alone does not,
2
+ # so a mistyped tag costs nothing and the release notes are written before anything ships.
3
+ #
4
+ # No token anywhere. PyPI Trusted Publishing exchanges this workflow's OIDC identity for a short-lived
5
+ # upload token, which is why `id-token: write` is here and no secret is. It has to be configured once
6
+ # on PyPI, under the project's Publishing settings (a pending publisher before the first release):
7
+ #
8
+ # owner ksallee
9
+ # repository sg-mockgun
10
+ # workflow release.yml
11
+ # environment pypi
12
+ #
13
+ # The `pypi` environment is the second half of that: with it set, only a run in that environment can
14
+ # claim the identity, so a workflow added by a pull request cannot publish.
15
+ #
16
+ # The version published is `[project].version` in pyproject.toml. PyPI refuses a version it already
17
+ # has, so bump it in the same commit as the release, and never re-point a tag at new code.
18
+
19
+ name: Release
20
+
21
+ on:
22
+ release:
23
+ types: [published]
24
+
25
+ permissions:
26
+ contents: read
27
+
28
+ jobs:
29
+ pypi:
30
+ name: Build and publish to PyPI
31
+ runs-on: ubuntu-latest
32
+ environment: pypi
33
+ permissions:
34
+ id-token: write
35
+ steps:
36
+ - uses: actions/checkout@v5
37
+
38
+ - uses: astral-sh/setup-uv@v7
39
+ with:
40
+ enable-cache: true
41
+
42
+ # Built from the tagged tree, because that is the tree being published.
43
+ - run: uv build
44
+
45
+ # The schemas are pickles inside the package: a wheel that lost them still imports, so this
46
+ # loads both and writes a record before anyone can install it.
47
+ - name: The wheel works before anyone can install it
48
+ run: |
49
+ python -m venv /tmp/v
50
+ /tmp/v/bin/pip -q install dist/*.whl
51
+ /tmp/v/bin/sg-mockgun --help > /dev/null
52
+ cd /tmp && /tmp/v/bin/python -c "
53
+ from sg_mockgun import Shotgun, schemas
54
+ for name in (None, 'upstream_3_10_5'):
55
+ Shotgun.set_schema_paths(*(schemas.paths(name) if name else schemas.paths()))
56
+ sg = Shotgun('https://mock.example.com', script_name='x', api_key='y')
57
+ assert sg.create('Project', {'name': 'x'})['id'] == 1, name
58
+ print('ok')
59
+ "
60
+
61
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,5 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ dist/
@@ -0,0 +1,55 @@
1
+ Copyright (c) 2026, Kevin Sallee
2
+ Copyright (c) 2009-2011, Shotgun Software Inc
3
+ All rights reserved.
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ - Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ - Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ - Neither the name of the Shotgun Software Inc nor the names of its
16
+ contributors may be used to endorse or promote products derived from this
17
+ software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
+
30
+ Portions of code (xml-rpc client libs from standard python distro):
31
+
32
+ Copyright (c) 1999-2002 by Secret Labs AB
33
+ Copyright (c) 1999-2002 by Fredrik Lundh
34
+
35
+ By obtaining, using, and/or copying this software and/or its
36
+ associated documentation, you agree that you have read, understood,
37
+ and will comply with the following terms and conditions:
38
+
39
+ Permission to use, copy, modify, and distribute this software and
40
+ its associated documentation for any purpose and without fee is
41
+ hereby granted, provided that the above copyright notice appears in
42
+ all copies, and that both that copyright notice and this permission
43
+ notice appear in supporting documentation, and that the name of
44
+ Secret Labs AB or the author not be used in advertising or publicity
45
+ pertaining to distribution of the software without specific, written
46
+ prior permission.
47
+
48
+ SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
49
+ TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
50
+ ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
51
+ BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
52
+ DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
53
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
54
+ ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
55
+ OF THIS SOFTWARE.
@@ -0,0 +1,173 @@
1
+ Metadata-Version: 2.5
2
+ Name: sg-mockgun
3
+ Version: 0.1.0
4
+ Summary: Mockgun, the in-memory Flow Production Tracking mock from shotgun_api3, extended with behaviour recorded by sg-groundtruth.
5
+ License: Copyright (c) 2026, Kevin Sallee
6
+ Copyright (c) 2009-2011, Shotgun Software Inc
7
+ All rights reserved.
8
+
9
+ Redistribution and use in source and binary forms, with or without
10
+ modification, are permitted provided that the following conditions are met:
11
+
12
+ - Redistributions of source code must retain the above copyright notice, this
13
+ list of conditions and the following disclaimer.
14
+
15
+ - Redistributions in binary form must reproduce the above copyright notice,
16
+ this list of conditions and the following disclaimer in the documentation
17
+ and/or other materials provided with the distribution.
18
+
19
+ - Neither the name of the Shotgun Software Inc nor the names of its
20
+ contributors may be used to endorse or promote products derived from this
21
+ software without specific prior written permission.
22
+
23
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
24
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
27
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
29
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
30
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
31
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33
+
34
+ Portions of code (xml-rpc client libs from standard python distro):
35
+
36
+ Copyright (c) 1999-2002 by Secret Labs AB
37
+ Copyright (c) 1999-2002 by Fredrik Lundh
38
+
39
+ By obtaining, using, and/or copying this software and/or its
40
+ associated documentation, you agree that you have read, understood,
41
+ and will comply with the following terms and conditions:
42
+
43
+ Permission to use, copy, modify, and distribute this software and
44
+ its associated documentation for any purpose and without fee is
45
+ hereby granted, provided that the above copyright notice appears in
46
+ all copies, and that both that copyright notice and this permission
47
+ notice appear in supporting documentation, and that the name of
48
+ Secret Labs AB or the author not be used in advertising or publicity
49
+ pertaining to distribution of the software without specific, written
50
+ prior permission.
51
+
52
+ SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
53
+ TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
54
+ ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
55
+ BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
56
+ DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
57
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
58
+ ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
59
+ OF THIS SOFTWARE.
60
+ License-File: LICENSE
61
+ Requires-Python: >=3.9
62
+ Requires-Dist: shotgun-api3>=3.10.5
63
+ Description-Content-Type: text/markdown
64
+
65
+ # sg-mockgun
66
+
67
+ Mockgun, the in-memory Flow Production Tracking mock that ships inside
68
+ [shotgun_api3](https://github.com/shotgunsoftware/python-api), taken out on its own and extended
69
+ with behaviour recorded by [sg-groundtruth](https://github.com/ksallee/sg-groundtruth).
70
+
71
+ Status: `0.1.0`. Mockgun as vendored from shotgun_api3 3.10.5, upstream tests passing, plus a clean
72
+ current schema, schema field writes, an event log, and an HTTP server a real client connects to.
73
+
74
+ ## Why
75
+
76
+ Upstream mockgun covers find, create, update, delete, revive and batch against a pickled schema. It
77
+ raises `NotImplementedError` on `schema_field_create`, `schema_field_update` and
78
+ `schema_field_delete`, and has no event log. A live site refuses a data type change, keeps a
79
+ deleted field's name taken and records every write in the event log. Code tested on mockgun never
80
+ meets those answers.
81
+
82
+ ## Event log
83
+
84
+ Every create, update, delete, revive and schema field write adds `EventLogEntry` rows shaped as the
85
+ site writes them (`docs/api3-probe-2026-11-12.md`, findings 025 and 049), queryable with `find`:
86
+
87
+ - A create logs `Shotgun_<Type>_New`, then one `_Change` per field it set, with `in_create: true`.
88
+ - An update logs one `_Change` per field whose value changed, `meta.old_value` and `meta.new_value`.
89
+ - A delete logs a `retirement_date` change and `_Retirement`, and drops the `entity` link from every
90
+ earlier row for that entity; `meta.entity_id` keeps the trail. A revive logs the reverse and `_Revival`.
91
+ - Field create, rename and delete log `Shotgun_DisplayColumn_*` rows.
92
+
93
+ `sg.generate_event_log_entries = False` turns logging off, as the ApiUser flag does on a site (default
94
+ on here, off on a site). `sg.set_clock(fn)` makes timestamps deterministic.
95
+
96
+ Not modelled: server-set defaults logged on create, the internal `properties` row a rename also
97
+ writes, and event ids that a site reserves ahead and commits late (finding 025).
98
+
99
+ ## Schema field writes
100
+
101
+ `schema_field_create`, `schema_field_update` and `schema_field_delete` answer as a Flow PT 8.91 site
102
+ answered over api3 (`docs/api3-probe-2026-11-12.md`), with `shotgun_api3.Fault` and the site's words:
103
+
104
+ - The code is `sg_` + the lowercased display name, non-alphanumerics to `_`. `sg_foo` becomes `sg_sg_foo`.
105
+ - A display name already taken by a live field is silently suffixed: `_1`, `_2`.
106
+ - A deleted field's code stays taken. Creating it again, at any type, is refused, and api3 has no revive.
107
+ - `data_type` cannot be updated. Only `name`, `visible`, `description`, `summary_default`,
108
+ `custom_metadata` and `unique` can.
109
+ - `query`, `summary`, `color` and `image` cannot be created. `calculated` fails as it does with no
110
+ formula. `entity` and `multi_entity` need one `valid_types`; `checkbox` needs a boolean default.
111
+ - Schema writes are per instance.
112
+
113
+ Two answers are not recorded over api3 and say so in the code: a `valid_types` with several types
114
+ uses the REST wording, and a `calculated` create carrying a formula is unmeasured.
115
+
116
+ ## Bundled schema
117
+
118
+ `sg_mockgun.schemas.paths()` returns a schema pulled from a Flow PT 8.91 site on 2026-11-12: 95
119
+ entity types, 1471 fields. Upstream's test schema predates `visible`, `calculated`, `summary` and
120
+ `jsonb` fields; this one has them.
121
+
122
+ It holds only what any site ships. `sg_mockgun.clean.clean_schema` keeps a field when the site cannot
123
+ hide it (`visible.editable` false, sg-groundtruth finding 056), when upstream's test schema has it, or
124
+ when its name carries no `sg_` prefix, since every custom field gets one (finding 019). Custom
125
+ entities the site enabled are dropped with their connection entities and every link to them.
126
+
127
+ `tools/pull_schema.py` pulls and cleans a schema from any site, read-only.
128
+
129
+ `schemas.paths("upstream_3_10_5")` is Autodesk's own test schema from shotgun_api3 3.10.5, as
130
+ published in its repository under BSD-3. Older (77 entity types, 1035 fields, no `visible` key), but
131
+ it ships with the client's own licence and covers the common production entities.
132
+
133
+ ## Use
134
+
135
+ pip install sg-mockgun
136
+
137
+ from sg_mockgun import Shotgun, schemas
138
+ Shotgun.set_schema_paths(*schemas.paths())
139
+ sg = Shotgun("https://mock.example.com", script_name="x", api_key="y")
140
+
141
+ ## Serve
142
+
143
+ sg-mockgun serve --host 0.0.0.0 --port 8080
144
+
145
+ import shotgun_api3
146
+ sg = shotgun_api3.Shotgun("http://localhost:8080", script_name="any", api_key="any")
147
+
148
+ One mockgun instance behind the api3 JSON protocol: `info`, `read` with paging, `create`, `update`,
149
+ `delete`, `revive`, `batch` and the `schema_*` calls. Any script name and key are accepted, and the
150
+ script name is the event log's user. Faults come back in the site's `exception` envelope; any other
151
+ method answers `Error: API method "<name>" is not permitted.`, as a site does. Calls are serialised
152
+ under one lock.
153
+
154
+ Next to api3 it serves the two REST routes a site needs to revive a trashed field, which api3
155
+ cannot do: `POST /api/v1/auth/access_token` (`client_credentials` with the script name and key,
156
+ `session_token` from `sg.get_session_token()`, `refresh_token`; form-encoded only) and
157
+ `POST /api/v1/schema/<Type>/fields/<field>` with `revive` true, in the body or the query. The field
158
+ comes back at its original type. Answers from sg-groundtruth finding 040 and its endpoint cards;
159
+ any other REST path is a 404. In-process, `sg.revive_field(entity_type, code)` does the same.
160
+
161
+ State lives in memory; `sg_mockgun.server.make_server(mock)` serves an instance you
162
+ have seeded yourself.
163
+
164
+ ## Develop
165
+
166
+ uv sync
167
+ uv run pytest
168
+
169
+ ## License
170
+
171
+ BSD-3-Clause, as upstream. `src/sg_mockgun/` started as `shotgun_api3/lib/mockgun` from
172
+ shotgun_api3 3.10.5, Copyright (c) 2009-2011 Shotgun Software Inc. `tests/test_upstream_mockgun.py`
173
+ and `tests/fixtures/upstream/` are upstream's tests and test schema, with import paths changed.
@@ -0,0 +1,109 @@
1
+ # sg-mockgun
2
+
3
+ Mockgun, the in-memory Flow Production Tracking mock that ships inside
4
+ [shotgun_api3](https://github.com/shotgunsoftware/python-api), taken out on its own and extended
5
+ with behaviour recorded by [sg-groundtruth](https://github.com/ksallee/sg-groundtruth).
6
+
7
+ Status: `0.1.0`. Mockgun as vendored from shotgun_api3 3.10.5, upstream tests passing, plus a clean
8
+ current schema, schema field writes, an event log, and an HTTP server a real client connects to.
9
+
10
+ ## Why
11
+
12
+ Upstream mockgun covers find, create, update, delete, revive and batch against a pickled schema. It
13
+ raises `NotImplementedError` on `schema_field_create`, `schema_field_update` and
14
+ `schema_field_delete`, and has no event log. A live site refuses a data type change, keeps a
15
+ deleted field's name taken and records every write in the event log. Code tested on mockgun never
16
+ meets those answers.
17
+
18
+ ## Event log
19
+
20
+ Every create, update, delete, revive and schema field write adds `EventLogEntry` rows shaped as the
21
+ site writes them (`docs/api3-probe-2026-11-12.md`, findings 025 and 049), queryable with `find`:
22
+
23
+ - A create logs `Shotgun_<Type>_New`, then one `_Change` per field it set, with `in_create: true`.
24
+ - An update logs one `_Change` per field whose value changed, `meta.old_value` and `meta.new_value`.
25
+ - A delete logs a `retirement_date` change and `_Retirement`, and drops the `entity` link from every
26
+ earlier row for that entity; `meta.entity_id` keeps the trail. A revive logs the reverse and `_Revival`.
27
+ - Field create, rename and delete log `Shotgun_DisplayColumn_*` rows.
28
+
29
+ `sg.generate_event_log_entries = False` turns logging off, as the ApiUser flag does on a site (default
30
+ on here, off on a site). `sg.set_clock(fn)` makes timestamps deterministic.
31
+
32
+ Not modelled: server-set defaults logged on create, the internal `properties` row a rename also
33
+ writes, and event ids that a site reserves ahead and commits late (finding 025).
34
+
35
+ ## Schema field writes
36
+
37
+ `schema_field_create`, `schema_field_update` and `schema_field_delete` answer as a Flow PT 8.91 site
38
+ answered over api3 (`docs/api3-probe-2026-11-12.md`), with `shotgun_api3.Fault` and the site's words:
39
+
40
+ - The code is `sg_` + the lowercased display name, non-alphanumerics to `_`. `sg_foo` becomes `sg_sg_foo`.
41
+ - A display name already taken by a live field is silently suffixed: `_1`, `_2`.
42
+ - A deleted field's code stays taken. Creating it again, at any type, is refused, and api3 has no revive.
43
+ - `data_type` cannot be updated. Only `name`, `visible`, `description`, `summary_default`,
44
+ `custom_metadata` and `unique` can.
45
+ - `query`, `summary`, `color` and `image` cannot be created. `calculated` fails as it does with no
46
+ formula. `entity` and `multi_entity` need one `valid_types`; `checkbox` needs a boolean default.
47
+ - Schema writes are per instance.
48
+
49
+ Two answers are not recorded over api3 and say so in the code: a `valid_types` with several types
50
+ uses the REST wording, and a `calculated` create carrying a formula is unmeasured.
51
+
52
+ ## Bundled schema
53
+
54
+ `sg_mockgun.schemas.paths()` returns a schema pulled from a Flow PT 8.91 site on 2026-11-12: 95
55
+ entity types, 1471 fields. Upstream's test schema predates `visible`, `calculated`, `summary` and
56
+ `jsonb` fields; this one has them.
57
+
58
+ It holds only what any site ships. `sg_mockgun.clean.clean_schema` keeps a field when the site cannot
59
+ hide it (`visible.editable` false, sg-groundtruth finding 056), when upstream's test schema has it, or
60
+ when its name carries no `sg_` prefix, since every custom field gets one (finding 019). Custom
61
+ entities the site enabled are dropped with their connection entities and every link to them.
62
+
63
+ `tools/pull_schema.py` pulls and cleans a schema from any site, read-only.
64
+
65
+ `schemas.paths("upstream_3_10_5")` is Autodesk's own test schema from shotgun_api3 3.10.5, as
66
+ published in its repository under BSD-3. Older (77 entity types, 1035 fields, no `visible` key), but
67
+ it ships with the client's own licence and covers the common production entities.
68
+
69
+ ## Use
70
+
71
+ pip install sg-mockgun
72
+
73
+ from sg_mockgun import Shotgun, schemas
74
+ Shotgun.set_schema_paths(*schemas.paths())
75
+ sg = Shotgun("https://mock.example.com", script_name="x", api_key="y")
76
+
77
+ ## Serve
78
+
79
+ sg-mockgun serve --host 0.0.0.0 --port 8080
80
+
81
+ import shotgun_api3
82
+ sg = shotgun_api3.Shotgun("http://localhost:8080", script_name="any", api_key="any")
83
+
84
+ One mockgun instance behind the api3 JSON protocol: `info`, `read` with paging, `create`, `update`,
85
+ `delete`, `revive`, `batch` and the `schema_*` calls. Any script name and key are accepted, and the
86
+ script name is the event log's user. Faults come back in the site's `exception` envelope; any other
87
+ method answers `Error: API method "<name>" is not permitted.`, as a site does. Calls are serialised
88
+ under one lock.
89
+
90
+ Next to api3 it serves the two REST routes a site needs to revive a trashed field, which api3
91
+ cannot do: `POST /api/v1/auth/access_token` (`client_credentials` with the script name and key,
92
+ `session_token` from `sg.get_session_token()`, `refresh_token`; form-encoded only) and
93
+ `POST /api/v1/schema/<Type>/fields/<field>` with `revive` true, in the body or the query. The field
94
+ comes back at its original type. Answers from sg-groundtruth finding 040 and its endpoint cards;
95
+ any other REST path is a 404. In-process, `sg.revive_field(entity_type, code)` does the same.
96
+
97
+ State lives in memory; `sg_mockgun.server.make_server(mock)` serves an instance you
98
+ have seeded yourself.
99
+
100
+ ## Develop
101
+
102
+ uv sync
103
+ uv run pytest
104
+
105
+ ## License
106
+
107
+ BSD-3-Clause, as upstream. `src/sg_mockgun/` started as `shotgun_api3/lib/mockgun` from
108
+ shotgun_api3 3.10.5, Copyright (c) 2009-2011 Shotgun Software Inc. `tests/test_upstream_mockgun.py`
109
+ and `tests/fixtures/upstream/` are upstream's tests and test schema, with import paths changed.
@@ -0,0 +1,119 @@
1
+ # api3 probe, 2026-11-12
2
+
3
+ Flow PT 8.91, shotgun_api3 3.10.5, one script user with `generate_event_log_entries` true. Writes:
4
+ throwaway `zzprobe mockgun` fields on Version (all deleted, names spent) and one Version in a sandbox
5
+ project (created, updated, deleted, revived, deleted). Ids, project and user are replaced with
6
+ placeholders. sg-groundtruth recorded the same behaviour over REST (findings 019, 025, 040, 049);
7
+ this file is the api3 wording mockgun reproduces.
8
+
9
+ ## Schema field writes
10
+
11
+ | call | answer |
12
+ |---|---|
13
+ | `schema_field_create("Version", "text", "zzprobe mockgun a")` | `"sg_zzprobe_mockgun_a"` |
14
+ | same again | `"sg_zzprobe_mockgun_a_1"`, no error |
15
+ | `schema_field_create("Version", "number", "sg_zzprobe mockgun b")` | `"sg_sg_zzprobe_mockgun_b"` |
16
+ | type `calculated`, no properties | Fault `API schema_field_create() NoMethodError: undefined method 'strip' for nil` |
17
+ | type `query`, `summary`, `color`, `image`, `nope` | Fault `API schema_field_create() can't create '<type>' data type. Valid data types:` + the list below |
18
+ | type `entity`, no `valid_types` | Fault `API schema_field_create() missing required 'properties' ["valid_types"]` |
19
+ | type `checkbox`, no `default_value` | Fault `API schema_field_create() Crud::ParameterError: Only true or false allowed in checkbox` |
20
+ | entity type `NotAType` | Fault `API schema_field_create() invalid/missing string entity 'type':` + the request + `Valid entity types:` + every entity type |
21
+ | `schema_field_update(..., {"data_type": "number"})` | Fault `API schema_field_update() invalid property 'data_type':` + `{"property_name" => "data_type", "value" => "number"}` + `Valid property names:` + `["name", "visible", "description", "summary_default", "custom_metadata", "unique"]` one per line |
22
+ | raw `schema_field_update` with `data_type` top level and empty `properties` | Fault `API schema_field_update() can't create/update with no 'properties':` + `[]` |
23
+ | `schema_field_update(..., {"name": ...})` | `True` |
24
+ | update, read or delete of a field that does not exist | Fault `API schema_field_<call>() Version.<code> doesn't exist:` + the request |
25
+ | `schema_field_delete` | `True` |
26
+ | create the deleted field's display name again, as `text` or `number` | Fault `API schema_field_create() failed, there is a retired field with the same field_name: <code>. Delete the retired field forever from the Trash Page in Shotgun and try again.` |
27
+ | raw `_call_rpc("schema_field_revive", ...)` | Fault `Error: API method "schema_field_revive" is not permitted.` |
28
+
29
+ Valid data types, as printed:
30
+
31
+ ```
32
+ ["calculated",
33
+ "checkbox",
34
+ "currency",
35
+ "date",
36
+ "date_time",
37
+ "duration",
38
+ "entity",
39
+ "float",
40
+ "footage",
41
+ "list",
42
+ "multi_entity",
43
+ "number",
44
+ "percent",
45
+ "status_list",
46
+ "text",
47
+ "timecode",
48
+ "url",
49
+ "uuid"]
50
+ ```
51
+
52
+ Over api3 a deleted field cannot come back: revive is REST only (`POST /schema/<Type>/fields/<code>`
53
+ with `{"revive": true}`, finding 040).
54
+
55
+ ## Event log
56
+
57
+ In id order. `<user>` is the script's display name, `<dc>` a DisplayColumn id, `<v>` the Version id.
58
+
59
+ Field create, rename, delete:
60
+
61
+ ```
62
+ Shotgun_DisplayColumn_New meta {type: new_entity, entity_type: DisplayColumn, entity_id: <dc>}
63
+ description "<user> created new Field sg_zzprobe_mockgun_a"
64
+ Shotgun_DisplayColumn_Change attribute human_name
65
+ meta {type: attribute_change, attribute_name: human_name, entity_type: DisplayColumn,
66
+ entity_id: <dc>, field_data_type: text, old_value: "zzprobe mockgun a",
67
+ new_value: "zzprobe mockgun a renamed"}
68
+ description '<user> changed "Field Name" from "zzprobe mockgun a" to "zzprobe mockgun a renamed" on Field sg_zzprobe_mockgun_a'
69
+ Shotgun_DisplayColumn_Change attribute properties (same update; old/new are internal property hashes)
70
+ Shotgun_DisplayColumn_Change attribute retirement_date meta old_value null, new_value "2026-11-12 21:54:08 UTC" (no field_data_type)
71
+ Shotgun_DisplayColumn_Retirement meta {entity_type: DisplayColumn, class_name: DisplayColumn, entity_id: <dc>, id: <dc>,
72
+ type: entity_retirement, retirement_date: "...", display_name: sg_zzprobe_mockgun_a}
73
+ description ' retired DisplayColumn "sg_zzprobe_mockgun_a"'
74
+ ```
75
+
76
+ Entity create with `code` and `description`, then update, delete, revive, delete:
77
+
78
+ ```
79
+ Shotgun_Version_New meta {type: new_entity, entity_type: Version, entity_id: <v>, platform_id: null}
80
+ description "<user> created new Version "
81
+ Shotgun_Version_Change one row per field the create set, server defaults included (code, sg_status_list,
82
+ sg_version_type, user, description), each meta {type: attribute_change, attribute_name,
83
+ entity_type, entity_id, in_create: true, field_data_type, old_value: null, new_value, platform_id: null}
84
+ Shotgun_Version_Change description "probe" -> "probe 2"; no row for sg_status_list written with the value it held
85
+ Shotgun_Version_Change retirement_date null -> "2026-11-12 21:54:11 UTC"
86
+ Shotgun_Version_Retirement meta {..., type: entity_retirement, retirement_date, display_name: <code>}
87
+ Shotgun_Version_Change retirement_date "..." -> null
88
+ Shotgun_Version_Revival meta {class_name, display_name, id, entity_type, entity_id, type: entity_revival}
89
+ description ' revived Version "<code>"'
90
+ ```
91
+
92
+ `_New` comes first, then the `_Change` rows of the same create. Change descriptions read
93
+ `<user> changed "<Field Display Name>" from "<old>" to "<new>" on <Type> <code>`, with `""` for null.
94
+
95
+ ## Revive from an api3 session, over REST
96
+
97
+ api3 has no field revive, but the same credentials reach REST. Recorded later the same day:
98
+
99
+ ```
100
+ sg.get_session_token() -> a session token
101
+ POST /api/v1/auth/access_token
102
+ grant_type=session_token, session_token=<token> -> 200 {token_type, access_token, expires_in, refresh_token}
103
+ POST /api/v1/schema/Version/fields/sg_sg_zzprobe_mockgun_b
104
+ {"revive": true}, Bearer <access_token> -> 204, empty body
105
+ sg.schema_field_read("Version", "sg_sg_zzprobe_mockgun_b") -> data_type number (its original type), name kept
106
+ sg.schema_field_delete(...) -> True (trashed again)
107
+ ```
108
+
109
+ Events for the revive:
110
+
111
+ ```
112
+ Shotgun_DisplayColumn_Change attribute retirement_date, meta old_value "2026-11-12 21:54:12 UTC", new_value null
113
+ Shotgun_DisplayColumn_Revival meta {class_name: DisplayColumn, display_name: <code>, id: <dc>, entity_type: DisplayColumn,
114
+ entity_id: <dc>, type: entity_revival}
115
+ description ' revived DisplayColumn "<code>"'
116
+ ```
117
+
118
+ `client_credentials` with the script name and key mints the same kind of token (sg-groundtruth
119
+ endpoint card post_auth_access_token). Field revive semantics: finding 040.
@@ -0,0 +1,21 @@
1
+ [project]
2
+ name = "sg-mockgun"
3
+ version = "0.1.0"
4
+ description = "Mockgun, the in-memory Flow Production Tracking mock from shotgun_api3, extended with behaviour recorded by sg-groundtruth."
5
+ readme = "README.md"
6
+ license = { file = "LICENSE" }
7
+ requires-python = ">=3.9"
8
+ dependencies = ["shotgun-api3>=3.10.5"]
9
+
10
+ [project.scripts]
11
+ sg-mockgun = "sg_mockgun.server:main"
12
+
13
+ [dependency-groups]
14
+ dev = ["pytest>=8"]
15
+
16
+ [build-system]
17
+ requires = ["hatchling"]
18
+ build-backend = "hatchling.build"
19
+
20
+ [tool.hatch.build.targets.wheel]
21
+ packages = ["src/sg_mockgun"]
@@ -0,0 +1,35 @@
1
+ """
2
+ -----------------------------------------------------------------------------
3
+ Copyright (c) 2009-2017, Shotgun Software Inc
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ - Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ - Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ - Neither the name of the Shotgun Software Inc nor the names of its
16
+ contributors may be used to endorse or promote products derived from this
17
+ software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
+
30
+ -----------------------------------------------------------------------------
31
+ """
32
+
33
+ from .schema import generate_schema # noqa
34
+ from .mockgun import Shotgun # noqa
35
+ from .errors import MockgunError # noqa
@@ -0,0 +1,59 @@
1
+ """Clean a schema read from a live site down to what any site ships. Pure: no I/O.
2
+
3
+ A field is kept when the site cannot hide it (``visible.editable`` false, sg-groundtruth finding 056)
4
+ or when upstream's test schema already carries it, which brings back the few stock template fields
5
+ that read hideable. Every custom field is named with an ``sg_`` prefix (finding 019), so a hideable
6
+ field without one, and not the reverse side of a custom link (``<type>_sg_...``), is stock too. Custom entities a site has enabled and renamed are dropped with every field and
7
+ connection entity that points at them; disabled custom entities stay, as they do on a fresh site.
8
+ """
9
+
10
+ import copy
11
+ import re
12
+
13
+ _CUSTOM_ENTITY = re.compile(r"^Custom(NonProject|Threaded)?Entity\d+$")
14
+ _CUSTOM_CONNECTION = re.compile(r"_sg_.*_Connection$")
15
+
16
+
17
+ def _hideable(field_def):
18
+ return field_def.get("visible", {}).get("editable", True)
19
+
20
+
21
+ def _custom_name(name):
22
+ return name.startswith("sg_") or "_sg_" in name
23
+
24
+
25
+ def _enabled_custom(name, entity_def):
26
+ return bool(_CUSTOM_ENTITY.match(name)) and entity_def.get("visible", {}).get("value", False)
27
+
28
+
29
+ def clean_schema(site_schema, site_entities, upstream_schema):
30
+ """Return ``(schema, entities, report)``; inputs are left untouched."""
31
+ dropped_entities = sorted(
32
+ name
33
+ for name in site_schema
34
+ if _enabled_custom(name, site_entities.get(name, {}))
35
+ or _CUSTOM_CONNECTION.search(name)
36
+ or any(name.startswith(c + "_") for c in site_schema if _enabled_custom(c, site_entities.get(c, {})))
37
+ )
38
+ gone = set(dropped_entities)
39
+
40
+ schema, dropped_fields = {}, []
41
+ for entity_type, fields in site_schema.items():
42
+ if entity_type in gone:
43
+ continue
44
+ upstream_fields = upstream_schema.get(entity_type, {})
45
+ kept = {}
46
+ for name, field_def in fields.items():
47
+ if _hideable(field_def) and name not in upstream_fields and _custom_name(name):
48
+ dropped_fields.append((entity_type, name))
49
+ continue
50
+ field_def = copy.deepcopy(field_def)
51
+ valid_types = field_def.get("properties", {}).get("valid_types")
52
+ if valid_types and isinstance(valid_types.get("value"), list):
53
+ valid_types["value"] = [t for t in valid_types["value"] if t not in gone]
54
+ kept[name] = field_def
55
+ schema[entity_type] = kept
56
+
57
+ entities = {k: copy.deepcopy(v) for k, v in site_entities.items() if k not in gone}
58
+ report = {"dropped_entities": dropped_entities, "dropped_fields": sorted(dropped_fields)}
59
+ return schema, entities, report