@anntzer: as you suggested, this PR is the first step in breaking up#16607 into several easier-to-merge chunks :)

I am 👍 on the enthusiasm! However, I have concerns about the unintended consequences.

Thanks for the positive feedback,@tacaswell !

It looks like the minimal fix to prevent the circular imports is to move thefrom .path import Path to be local tomake_path_regular andconcatenate_paths

Even easier, I made them just wrap the appropriate method calls (of the.Path object). This technically could be a breaking change if a user was abusing duck typing to use these functions for a non-Path-subclass that happened to implement similarly-named methods....but I assume there is less concern about impacting users that crossthat threshold of cleverness?

we can not move them with no warning.

Would you be more in favor of slowly deprecating these functions? I obviously don't mind them being perpetually duplicated inbezier.py personally, but I went ahead and pushed up a version with some deprecation warnings.

Actually, I am deprecating make_path_regular and concatenate_paths in#14199; can that get reviewed first? Both functions actually have relatively simple alternatives available.

@tacaswell , what is the expectation before merging, should this branch be rebased to be a single commit? Or do you prefer to preserve the whole commit history?

If you make 50 commits where one would do (e.g., if there are multiple test image changes), we'd ask to squash, but otherwise we don't bother.

This PR is now ready for re-review pending merge of#14199.

After that#14199 is merged, this PR will basically just:

1. deprecate bezier.split_path_inout in favor of path.Path.split_path_inout
2. deprecate bezier.inside_circle (only used by patches.py)
3. various doc cleanups I found while documenting these deprecations

This PR is required to begin fixing#16606,#16830, and#7184.

Squashed all commits into one, since a bunch of other PRs depend on this, to make it easier to review them.

I agree we need to step back and get a broader view of what we are doing here.

While it's easy to see how this could happen, this dependency should pretty obviously be reversed.bezier.py

I do not agree it is obvious,bezier can be seen as specialized version of path.

and all computations that are "about paths" should be inclass Path.

Again, I'm not sure that this is obvious. I am assuming that these helpers are things that only need to use the public API ofPath to do their job? If that is the case, we may want to have many more helpers that work onPath objects than we want to put as part of the public API ofPath.

I think we could we avoid the need for this re-arrangement if we make a_marker_path_helpers.py that can import both.path and.bezier and inmarkers import.path (as we do now) and_marker_path_helpers. Once that is all done, then we can circle back to decide which of those helpers we to promote to being methods on the Path object.

In addition to avoiding this code churn, starting with the helpers in a private module lets us be less careful about merging things and in changing what is there independent of how the totality of this work gets relative to version releases etc.

Again I am 👍 on this work in principle and looking for the path of least resistance to getting this code in.

I agree we need to step back and get a broader view of what we are doing here.

Thanks as usual for the positive feedback! I have opened a PR (#16891) with one proposed architecture for the new changes. I think a lot of this discussion would best take place there, and this PR can be revisited once we're all on the same page as to the best top-level architectural decisions for how to add this new code.

I'll answer your comments here for the record, but will reproduce these points in#16891, so we can continue the discussion there.

While it's easy to see how this could happen, this dependency should pretty obviously be reversed.bezier.py

I do not agree it is obvious,bezier can be seen as specialized version of path.

You're right, obvious was the wrong word. There are two equally-valid interpretations of the relationship ofbezier andpath, which imply opposite directions of dependency:
1) a Path's are made up of BezierSegments, sopath shouldfrom .bezier import any functions that it needs for computing things about Paths.
2) a BezierSegment is just a Path with one code. Sobezier.py should contain...helper functions for simple paths that are commonly found in the bezier literature, but should rely onfrom .path import'ing anything that Path already does (?)

What this PR is implicitly proposing is that the most natural way to architect this library going forward is to commit to (1). This is because anything you want to compute about a path (arc length, area, bounding box, etc) you do it by computing it for each BezierSegment making up the path. And if you go with (2) instead, then you have to end up pollutingpath.py with a bunch of code that should by all rights be methods ofBezierSegment (e.g. if we go with (2), we have functions likepath.bezier_length instead ofbezier.BezierSegment.length becausepath.py can't import frombezier.py).

and all computations that are "about paths" should be inclass Path.

Again, I'm not sure that this is obvious. I am assuming that these helpers are things that only need to use the public API ofPath to do their job? If that is the case, we may want to have many more helpers that work onPath objects than we want to put as part of the public API ofPath.

I think we could we avoid the need for this re-arrangement if we make a_marker_path_helpers.py that can import both.path and.bezier and inmarkers import.path (as we do now) and_marker_path_helpers. Once that is all done, then we can circle back to decide which of those helpers we to promote to being methods on the Path object.

I definitely agree that all of this extra code could for now be put into a private module, like_marker_path_helpers. Let's discuss in #... what should eventually be private and public. What this PR was implicitly proposing was that all of these new functions I'm writing (e.g.Path.signed_area,Path.length,Path.center_of_mass, etc), while being useful formarkers.py, were also performant enough and broadly applicable enough that they might be worth having in the public API ofPath.

If we decide thatnone of these functions eventually need to be public, then I will (reluctantly lol) close this PR and move all of my new code into a private helper module.

Given that this enables#16832 which has a concrete use to fix a bug, and there wasmostly agreement on the last call for this one, I'm not sure we need to hold this up for the more abstractMarkerStyle changes. But we can leave it for the call to hash out again.

Based on feedback from the call today, this PR has been changed to not actually perform any API changes. A new PR will be created with proposed API changes independently of this PR stack, which will now only contain feature improvements.

... since the deprecations went in, this is a trivial re-arrangements of the imports in the two deprecated methods.

just waiting for ci

The commit message was a bit weird, since it's not a backport of anything. I used a squash merge so I could change the message without having to wait for all the CI to re-run needlessly. Unfortunately, this does mean the other PRs need rebasing.

@QuLogic, thanks for fixing that, the commit message only made sense in the context of my personal branches.