Schema #3

Jrice1317 · 2025-09-26T19:35:44Z

Description

Provide metadata to easily protect environments (INST-622)

Related tickets:

Create frozen_environments metadata (INST-635)
Enable metadata for SH and PKG installers (INST-636)
Enable metadata for EXE installers (INST-637)
Extend integration tests for the new metadata (INST-638)

Checklist - did you ...

Add a file to the news directory (using the template) for the next release's release notes?
Add / update necessary tests?
Add / update outdated documentation?

constructor/_schema.py

marcoesters · 2025-10-08T19:46:37Z

constructor/_schema.py

+    - `None` (default): Does not protect the `base` environment.
+    - `dict`: The `base` environment will be protected. An empty dict will generate a default message. Otherwise, the content of the dictionary will result in a custom message.


If I read this, I would think that I could write a literal None, which is not correct. I would focus the description on that this is the content of the frozen file without going into the details about what they may contain (or you have to maintain the documentation about the file format). You can just refer to the CEP for details.

Something like:

The content of the frozen file marker (see CEP-22 for details). If not used, the base environment will not be protected.

constructor/_schema.py

marcoesters

I think the code and documentation are in need of simplification. It also looks like the tests aren't passing.

marcoesters · 2025-11-18T14:56:51Z

constructor/_schema.py

+    message: NonEmptyStr | None = None
+    "Custom message to display when the environment is frozen."
+
+    error: NonEmptyStr | None = None


error is not a recognized field in a frozen file.

Thanks for catching this! I thought removed all instances of error.

marcoesters · 2025-11-18T14:59:48Z

constructor/_schema.py

    "Target channel, after being mapped"


+class FreezeEnvConfig(BaseModel):


I don't think we should specify the fields here because this would commit us to keeping up with changes to the file specification, even if you allow for extra fields. I'd just use dict as the type and be done with it.

marcoesters · 2025-11-18T15:03:26Z

constructor/main.py

        "conclusion_file",
        "signing_certificate",
-        "post_install_pages",
+        "post_install_pages"


Please revert this. Trailing commas are standard.

Typo from removing something else. Thanks!

marcoesters · 2025-11-18T15:04:46Z

constructor/main.py

-                and path.parts[0] == "envs"
-                and path.parts[-2:] == ("conda-meta", "frozen")
-            )
+    # Frozen environments from freeze_base and freeze_env


This entire logic is getting very unwieldy. I think it's time to create a separate function (like validate_frozen) to perform all frozen environment validation.

marcoesters · 2025-11-18T15:06:17Z

constructor/main.py

+        frozens
        and exe_type == StandaloneExe.CONDA
-        and check_version(exe_version, min_version="25.5.0", max_version="25.7.0")
+        and not check_version(exe_version, min_version="25.7.0")


This is incorrect. conda-standalone 25.5.x is the only version that can't handle this. The error text is misleading.

marcoesters · 2025-11-18T15:28:54Z

constructor/_schema.py

    Use the standalone binary to perform the uninstallation on Windows.
    Requires conda-standalone 24.11.0 or newer.
    """
+    freeze_base: dict[Literal["conda"], FreezeEnvConfig] | None = None


The documentation could be significantly condensed and doesn't specify the general case. The reason why we have the conda key is because we will, I think, eventually expand this to other package managers like pip. So, the first paragraph should consist of something like "Protects the conda environment against modifications. Supported formats are:", and then talk about the different supported package managers (which is just conda right now).

marcoesters · 2025-11-18T15:30:15Z

constructor/_schema.py

+      - An empty dictionary `{}` to create an empty frozen marker file and receive the default message
+      - A non-empty dictionary with desired content (i.e. message or other key-value pairs) to customize the frozen marker file
+
+    The dictionary content is written as-is to the frozen marker file.


This can be condensed to just say that the value is a dictionary that will be written into the frozen marker file. We don't have to explain the format to them - CEP-22 does that already.

marcoesters · 2025-11-18T15:31:31Z

constructor/_schema.py

+
+    The dictionary content is written as-is to the frozen marker file.
+
+    Alternatively, you can provide your own pre-created frozen marker file using the `extra_files` option. If both `freeze_base` and a custom frozen marker file listed under `extra_files` are provided for the same environment, the custom file will take precedence.


I think we can just write this as a warning that extra_files will overwrite the frozen file. If we raise a runtime error though, this paragraph can be removed entirely.

I wouldn't remove it entirely even if we did raise an error, but I will shorten it a bit. I think it's nice for our users to make this note explicitly.

What is the advantage of keeping it? The point of the metadata expansion is to provide a canonical way to protect environments. I don't think adding additional non-canonical ways to do the same task adds to clarity. We don't do the same for the condarc key for the same reason.

marcoesters · 2025-11-18T15:32:04Z

constructor/_schema.py

+
+    Alternatively, you can provide your own pre-created frozen marker file using the `extra_files` option. If both `freeze_base` and a custom frozen marker file listed under `extra_files` are provided for the same environment, the custom file will take precedence.
+
+    If none of the above are provided, the environment will not be protected.


I think that part is clear based on what that property does.

marcoesters · 2025-11-18T15:33:00Z

constructor/_schema.py

+    Example for default:
+    ```yaml
+    freeze_base:
+        conda: {}
+    ```
+
+    Example for custom content:
+    ```yaml
+    freeze_base:
+        conda:
+            message: "This `base` environment is frozen and cannot be modified."
+    ```


This is pretty much the same example. It just looks different because YAML doesn't have a different way to write an empty dictionary.

Not quite, but yes, they do look very similar.

The second example doesn't add significantly new information, especially since there isn't a "default frozen file". I think one example with the message is good enough for brevity.

Co-authored-by: jaimergp <jaimergp@users.noreply.github.com>

Co-authored-by: Marco Esters <mesters@anaconda.com>

…o schema

Jrice1317 force-pushed the schema branch 2 times, most recently from 38f598a to 40e7c40 Compare October 3, 2025 22:13

marcoesters reviewed Oct 8, 2025

View reviewed changes

Jrice1317 commented Oct 9, 2025

View reviewed changes

constructor/_schema.py Outdated Show resolved Hide resolved

Jrice1317 requested a review from marcoesters November 17, 2025 23:39

marcoesters requested changes Nov 18, 2025

View reviewed changes

Jrice1317 and others added 17 commits November 19, 2025 01:26

Implement version check for frozen env

10aad99

First attempt at testing

88315e6

Fix version check

c954889

Fix test

09152d6

Change source in extra files mapping to use empty json

677698c

Only search extra_files for frozen file and xfail if version is 25.5.x

c70ef62

Handle str and dict instances

d135952

Add helper function for version ranges

94accfa

Remove stray comma

992af0d

Fix pre-commit errors

9cb539f

Use path for frozen file search

866dade

Add news file

ad334c6

Pre-commit fixes

5615614

Apply suggestions from code review

f75f091

Co-authored-by: jaimergp <jaimergp@users.noreply.github.com>

Apply suggestions from code review

bca0985

Co-authored-by: Marco Esters <mesters@anaconda.com>

Expand test to test base and extra envs

b69a76f

Fix pre-commit

01c1190

Jrice1317 force-pushed the metadata branch from 86cd620 to 01c1190 Compare November 19, 2025 09:49

Jrice1317 added 6 commits November 19, 2025 01:55

First attempt at testing

3caf37f

Only search extra_files for frozen file and xfail if version is 25.5.x

f2705d0

Add metadata for frozen environments in schema

4a33ef5

Update schema with added metadata

765f80c

Provide three different datatypes

f430db8

produce JSON file from schema

317aaa7

Jrice1317 and others added 25 commits December 4, 2025 09:31

Run scripts

a184580

Use sets instead

6999bae

Apply suggestions from code review

2ef49e2

Co-authored-by: Marco Esters <mesters@anaconda.com>

Address peer review comments

2392030

Update docs

b4beeb1

First attempt at testing

8cf49ec

Add metadata for frozen environments in schema

c699ff9

Provide three different datatypes

9fd2297

Remove whitespace

baace3d

Update config

57cd4f7

Update docs

aed94c6

Apply suggestions from code review

236f399

Co-authored-by: Marco Esters <mesters@anaconda.com>

Update wording of description per review suggestion

3aecd64

Co-authored-by: Marco Esters <mesters@anaconda.com>

Updata schema to address new design choice

efc7743

Add model for validation to help catch user errors early

e494074

Update example construct.yaml to latest design choice

2a70075

Remove extra field in custom dict example

5fa9e56

Update docstrings

d33dbbb

Update example construct.yaml

fb1b0eb

Update docs

4c5a0a1

Revert test and example

aa2d1cb

Apply suggestions from code review

7b65f39

Co-authored-by: Marco Esters <mesters@anaconda.com>

Address review comments

123588d

Merge branch 'schema' of https://github.com/Jrice1317/constructor int…

a2aada4

…o schema

Run scripts to update docs

0e3c96a

Jrice1317 requested a review from marcoesters December 4, 2025 19:22

Remove double check for frozen files

4bd6fb9

marcoesters approved these changes Dec 4, 2025

View reviewed changes

Jrice1317 merged commit 7b959d9 into metadata Dec 4, 2025
17 checks passed

Jrice1317 deleted the schema branch December 7, 2025 15:54

		- `None` (default): Does not protect the `base` environment.
		- `dict`: The `base` environment will be protected. An empty dict will generate a default message. Otherwise, the content of the dictionary will result in a custom message.

		"Target channel, after being mapped"


		class FreezeEnvConfig(BaseModel):


		The dictionary content is written as-is to the frozen marker file.

		Alternatively, you can provide your own pre-created frozen marker file using the `extra_files` option. If both `freeze_base` and a custom frozen marker file listed under `extra_files` are provided for the same environment, the custom file will take precedence.


		Alternatively, you can provide your own pre-created frozen marker file using the `extra_files` option. If both `freeze_base` and a custom frozen marker file listed under `extra_files` are provided for the same environment, the custom file will take precedence.

		If none of the above are provided, the environment will not be protected.

Schema #3

Schema #3

Uh oh!

Conversation

Jrice1317 commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related tickets:

Checklist - did you ...

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marcoesters left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Jrice1317 commented Sep 26, 2025 •

edited

Loading