feat: update deprecations

[nstarman]

After #175 and #173 were / will be merged I took a look and noticed some small improvements.
This PR moves Val out of __all__ and applies the https://peps.python.org/pep-0702/ deprecated decorator to make the deprecations visible to static analyzers.

Hm. Maybe I should move the stuff from here to #173 ?
Also, this PR is a good example of why the edit button on files in GH is not a great way to make a PR.

[coveralls]

Pull Request Test Coverage Report for Build 9718124559

Details

• 5 of 5 (100.0%) changed or added relevant lines in 3 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.001%) to 99.921%

---

Totals
Change from base Build 9716367696:	0.001%
Covered Lines:	1257
Relevant Lines:	1258

---

💛 - Coveralls

[wesselb]

Ah, I like this. Should this replace the warning.warn calls? I believe the decorator also raises a warning.

[coveralls]

Pull Request Test Coverage Report for Build 9725896976

Details

• 5 of 5 (100.0%) changed or added relevant lines in 3 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 99.92%

---

Totals
Change from base Build 9723266109:	0.0%
Covered Lines:	1255
Relevant Lines:	1256

---

💛 - Coveralls

[coveralls]

Pull Request Test Coverage Report for Build 9753685972

Details

• 5 of 5 (100.0%) changed or added relevant lines in 3 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 99.92%

---

Totals
Change from base Build 9741547843:	0.0%
Covered Lines:	1255
Relevant Lines:	1256

---

💛 - Coveralls

[PhilipVinc]

LGTM. I'm happy to discover about typing_extensions.deprecated.

By the way @wesselb , a thing that always bothered me about plum is that we have a severely polluted namespace and several modules exposed which are unclear how public they are:

In [1]: import plum

In [2]: plum.[/tab/tab]
  deactivate_union_aliases() dispatcher                 get_context()              isinstance()               List                       multihash()
  Dict                       Function                   get_overloads()            issubclass()               method                     NotFoundLookupError
< dispatch                   function                   is_faithful()              Kind                       Missing                    overload()                 >
  Dispatcher                 get_class()                is_in_class()              kind()                     ModuleType                 parametric()

I think one thing that might be helpful down the line would be to move everything to a _src module, and expose just few things in the main namespace...

[wesselb]

@PhilipVinc Hmmm, you’re totally right. It would be considerable improvement to better structure what’s exported where. I agree that the namespace currently is polluted. I’ve noted this down! Thanks! :)

@nstarman, thanks for yet another super clean PR!! I really do appreciate the many small, very well structured PRs. You’ve contributed a lot of improvements lately. :) This also looks great, so merging right away.