feat(python): expose cat.ordered

[ritchie46]

#5671

[ritchie46]

Somehow the docs fail because the self._s is not initialized in the CatNameSpace. This is probably because of our complicated dispatch.

Any idea here @alexander-beedie?

[alexander-beedie]

Any idea here @alexander-beedie?

Am currently in the middle of the Jordanian desert! 😂 Will be back in range of a computer on Monday evening if you can wait a bit - I'm sure it'll be something simple to resolve (quick sanity check: the CatNameSpace has the same decorator as the others?)

[ritchie46]

ning if you can wait a bit - I'm sure it'll be something simple to resolve (quick sanity check: the CatNameSpace has the same decorator as the others?)

No hurry at all! Have fun there in the dessert. ;)

[alexander-beedie]

Any idea here @alexander-beedie?

Refreshed; back home from... Mars?! (Feel like I should watch Dune again - part of it was shot out there ;)

Ok, so should be able to fix like so:

return self._s.cat_is_ordered() if self._s is not None else None

The reason is that the *NameSpace classes are accessed with an uninitialised Series from Sphinx (via the @accessor decorator in series.py which makes the namespaces available under the correct alias when docs are built). So, when the property is introspected by Sphinx (and only then) _s is still None, hence the error.

Could equally check the docs-build env var and return None if it is set:

if os.getenv("BUILDING_SPHINX_DOCS"):
    return None
return self._s.cat_is_ordered()

[ritchie46]

Wow, that's some sight indeed. How did my @alexander-beedie tag even reach you there? :see_no_evil:

[alexander-beedie]

Wow, that's some sight indeed. How did my @alexander-beedie tag even reach you there? 🙈

Heh... there was one spot in the camp with limited WiFi, so could check-up on the outside world at dinner/breakfast, lol.

I see the proposed fix didn't quite work; not sure why it's claiming to want a method signature out of a None value property, but can dig further tonight.

[alexander-beedie]

Hmm... I setup a debug profile for sphinx-build so I could step through and see what's happening; have tried several increasingly-exotic attempts to keep it happy, but the least-intrusive solution so far is simply to omit the @property decorator and leave it as a method - at which point everything appears to flow through smoothly (and you can drop the special None-handling code inside the method body):

def ordered(self) -> bool:
    """Return if sorting uses the categories or the lexical order of the string values."""  # noqa: E501
    return self._s.cat_is_ordered()

(Update: just had one last idea to potentially maintain as a property - will see if it's viable tomorrow morning).

[alexander-beedie]

The final idea "almost" worked - was playing with a @namespace_property decorator (a slight variation on @accessor) and that allowed the docs to compile fine without any other special handling, but with one irritating issue - the generated docs reported the ordered attribute as a method. It seems the universe really wants this to be a method...😅

[alexander-beedie]

I take it back - have managed to make a patch on top of this one that allows us to better-handle namespaced attributes, if you want to grab it; can take a look here: https://github.com/pola-rs/polars/commit/ebebd67e94d604b4e5f1eb4224ecb0608077ec9f. Allows us to use @property as normal, with no special handling, without raising sphinx-build errors.

The docs formatting as a method (above) came down to use of the wrong .rst accessor template, so that was an easy fix after all. The one thing that's still a bit annoying is that the description/docstring and expected type aren't being pulled into the generated docs; instead it's reporting the default attribute value (False). I can revisit this later to see if the template needs updating, or if there is something else at play, but at least it's in better shape now.

So, now have a reasonable choice between making it a method (everything works), or leaving as an attribute (everything works except for getting the complete description/docstring in the docs output).

[alexander-beedie]

@ritchie46: let's just make ordered a method - path of least resistance, and everything will "just work". (I can potentially revisit after upgrading to sphinx v6).

[stinodego]

Closing in favor of #10325 as I didn't feel like rebasing 😄