feat: Add support for opaque Schema handles in Python

[swenger]

Summary

Adds Schema, Schema.from_str, and Schema.from_json_str, following the same pattern as PolicySet and Entities.

Motivation

The same schema is usually passed to many different function calls, and each call parses it again. Pre-parsing the schema once into the (already existing) Rust Schema object lets us deduplicate this effort.

[Iamrodos]

@swenger Looking good. Are you intending updates to the README documentation?

[swenger]

Looking good.

Thanks :)

Are you intending updates to the README documentation?

Good idea - give me a minute and I'll get back to you.

[swenger]

Are you intending updates to the README documentation?

Good idea - give me a minute and I'll get back to you.

@Iamrodos how's 82d2275?

[skuenzli]

Thank you for the PR @swenger! I think this is a good idea. I will review my morning.

[skuenzli]

Thanks @swenger — overall this PR looks good and is a strong performance win. The Schema handle follows the PolicySet/Entities handle conventions nicely: frozen, eager ValueError on construction, Source-first extraction in SchemaArg, and the string/dict paths unchanged. Tests pass locally and CI is green.

There are a few issues to resolve first:

• Per-call Schema::clone() on the hot path. cedar_policy::Schema is not Arc-wrapped; it owns a ValidatorSchema full of HashMaps, so .cloned() is a deep copy. Both is_authorized_batch (schema_opt_for_entities.cloned()) and is_authorized_partial (schema_ref.cloned()) pay it on every call, including the plain-string path where no clone existed before. The handle is still a big win: I measured ~3,100µs down to ~55µs per call with a 300-entity-type schema. But the leftover clone cost grows with schema size (about 200µs/call at 3,000 entity types), and that's exactly the per-call cost this PR sets out to remove. It also runs inside the t_load_entities timer, so it inflates load_entities_duration_micros while parse_schema_duration_micros reads 0. The fix is to pass Option<&Schema> through EntitiesArg::resolve/resolve_partial, make_entities, load_entities, and execute_authorization_request instead of building an owned Option<Schema>; every downstream use only needs a reference. The clone in validate_policies is fine, since Validator::new takes Schema by value.
• Typed API and code documentation. Please add the Schema class to cedarpy/_internal.pyi and widen the schema parameters there (currently still Optional[str]); typed callers won't see the new API otherwise. Please also mention the handle in the :param schema docstrings of the three authorization functions in cedarpy/__init__.py, matching how the policies and entities params document theirs.
• Changelog. Please add an entry under [Unreleased] in CHANGELOG.md, following the pattern of the PolicySet/Entities handle entries.

Do you have any questions about the requested changes? Or would you like me to take care of any of them?

[swenger]

Thanks @skuenzli for the detailed feedback! Glad you caught the clones, which I completely missed...

Do you have any questions about the requested changes?

I don't think so, your explanations were great! Do the following commits address your concerns?

• Per-call Schema::clone() on the hot path. 3aa0a99
• Typed API and code documentation. 893a0f2 / aff5f10
• Changelog. a7f83ff

[skuenzli]

Looks great @swenger - thank you!

I upgraded the Schema __str__ and __repr__ implementations to parity with Entities and PolicySet.

I also credited you in the changelog entry.

[skuenzli]

Verified the clone fix locally — the handle path's per-call cost is now flat regardless of schema size. Before the fix it scaled linearly, because each call paid a deep copy of the ValidatorSchema.

Measured with release builds, pre-parsed PolicySet/Entities handles, so schema handling is the only variable:

Schema (as handle)	Before fix	After fix
none (baseline)	32.6 µs/call	33.0 µs/call
~4 entity types	33.7 µs/call	34.5 µs/call
300 entity types	51.2 µs/call	34.2 µs/call
3,000 entity types	199.5 µs/call	35.4 µs/call

The metrics are honest now too: load_entities_duration_micros previously absorbed the hidden clone (368µs on a call with a pre-parsed Entities handle); it now reads 0. For context, passing the 300-entity-type schema as a string costs ~3,100µs/call, so the handle is roughly a 90× reduction on that workload.

[swenger]

Thanks @skuenzli for the review and your additions!

Could you tag a release? I'd then package it for conda-forge.

[skuenzli]

Yes, kicking off the release process now.

[skuenzli]

@swenger the new Schema handle is now available in the new cedar-py v4.8.7 release

[swenger]

@swenger the new Schema handle is now available in the new cedar-py v4.8.7 release

Awesome, thanks @skuenzli!

[skuenzli]

Thank you @swenger ! Have a great weekend!