feat(ops): add accessor APIs tree_flatten_with_accessor and PyTreeSpec.accessors

[XuehaiPan]

Description

Describe your changes in detail.

This PR adds a new method accessors to PyTreeSpec objects.

The path to a leaf node is a tuple of entries, where an entry can be a raw index or dictionary key.

The newly added accessor will associate the corresponding node type to the entry. An accessor to a leaf node is a tuple of triples (entry, type, kind). For example:

In [1]: from collections import *

In [2]: MyTuple = namedtuple('MyTuple', ['x', 'y', 'z'])

In [3]: tree = OrderedDict([('a', (1, 2)), ('b', {'c': [3, 4], 'd': 5}), ('e', MyTuple(6, 7, 8))])

In [4]: import optree

In [5]: treespec = optree.tree_structure(tree)

In [6]: treespec
Out[6]: PyTreeSpec(OrderedDict([('a', (*, *)), ('b', {'c': [*, *], 'd': *}), ('e', MyTuple(x=*, y=*, z=*))]))

In [7]: treespec.paths()
Out[7]: [('a', 0), ('a', 1), ('b', 'c', 0), ('b', 'c', 1), ('b', 'd'), ('e', 0), ('e', 1), ('e', 2)]

In [8]: treespec.accessors()
Out[8]: 
[
    PyTreeAccessor(*['a'][0], (MappingEntry(key='a', type=<class 'collections.OrderedDict'>), SequenceEntry(index=0, type=<class 'tuple'>))),
    PyTreeAccessor(*['a'][1], (MappingEntry(key='a', type=<class 'collections.OrderedDict'>), SequenceEntry(index=1, type=<class 'tuple'>))),
    PyTreeAccessor(*['b']['c'][0], (MappingEntry(key='b', type=<class 'collections.OrderedDict'>), MappingEntry(key='c', type=<class 'dict'>), SequenceEntry(index=0, type=<class 'list'>))),
    PyTreeAccessor(*['b']['c'][1], (MappingEntry(key='b', type=<class 'collections.OrderedDict'>), MappingEntry(key='c', type=<class 'dict'>), SequenceEntry(index=1, type=<class 'list'>))),
    PyTreeAccessor(*['b']['d'], (MappingEntry(key='b', type=<class 'collections.OrderedDict'>), MappingEntry(key='d', type=<class 'dict'>))),
    PyTreeAccessor(*['e'].x, (MappingEntry(key='e', type=<class 'collections.OrderedDict'>), NamedTupleEntry(field=0, type=<class '__main__.MyTuple'>))),
    PyTreeAccessor(*['e'].y, (MappingEntry(key='e', type=<class 'collections.OrderedDict'>), NamedTupleEntry(field=1, type=<class '__main__.MyTuple'>))),
    PyTreeAccessor(*['e'].z, (MappingEntry(key='e', type=<class 'collections.OrderedDict'>), NamedTupleEntry(field=2, type=<class '__main__.MyTuple'>)))
]

In [9]: treespec.paths()[0]
Out[9]: ('a', 0)

In [10]: treespec.accessors()[0]
Out[10]:
PyTreeAccessor(*['a'][0], (MappingEntry(key='a', type=<class 'collections.OrderedDict'>), SequenceEntry(index=0, type=<class 'tuple'>)))

Motivation and Context

Why is this change required? What problem does it solve?
If it fixes an open issue, please link to the issue here.
You can use the syntax close #15213 if this solves the issue #15213

• I have raised an issue to propose this change (required for new features and bug fixes)

• [pytree] implement key path API pytorch/pytorch#113378

Types of changes

What types of changes does your code introduce? Put an x in all the boxes that apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds core functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (update in the documentation)

Checklist

Go over all the following points, and put an x in all the boxes that apply.
If you are unsure about any of these, don't hesitate to ask. We are here to help!

• I have read the CONTRIBUTION guide. (required)
• My change requires a change to the documentation.
• I have updated the tests accordingly. (required for a bug fix or a new feature)
• I have updated the documentation accordingly.
• I have reformatted the code using make format. (required)
• I have checked the code using make lint. (required)
• I have ensured make test pass. (required)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (10842aa) to head (b089dad).
Report is 25 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #108    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            9        10     +1     
  Lines          787       986   +199     
==========================================
+ Hits           787       986   +199     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stroxler]

The API shape here looks pretty good to me, I think it meets the needs discussed in
pytorch/pytorch#113378