7128155b28
Fix typos ( #251 )
...
Co-authored-by: Michael Howitz <mh@gocept.com>
2022-01-25 08:12:30 +01:00
077ff5b322
Fix the documentation so it can be tested with `ZOPE_INTERFACE_STRICT_IRO=1`. ( #242 )
...
Closes #241 .
2021-05-05 15:28:09 +02:00
eb542a8a75
Make Declaration.__add__ try harder to produce consistent resolution orders.
...
By moving things from the RHS to the front of the list if they already extend something from the LHS.
Fixes #193
2021-04-01 07:11:26 -05:00
ce8f66f8bf
Update repr() and str() of some common objects.
...
Only InterfaceClass got a str, so it now has a distinction. Other objects only got updated reprs.
Note: This may potentially break some doctests.
In many cases, the ``repr()`` is now something that can be evaluated
to produce an equal object. For example, what was previously printed
as ``<implementedBy builtins.list>`` is now shown as
``classImplements(list, IMutableSequence, IIterable)``.
Fixes #236
Here's a before with ZOPE_INTERFACE_LOG_CHANGED_IRO=1 in BTrees:
```
Object <implementedBy builtins.list> has different legacy and C3 MROs:
Legacy RO (len=11) C3 RO (len=11; inconsistent=no)
==================================================================================================================================================
<implementedBy builtins.list> <implementedBy builtins.list>
<ABCInterfaceClass zope.interface.common.collections.IMutableSequence> <ABCInterfaceClass zope.interface.common.collections.IMutableSequence>
<ABCInterfaceClass zope.interface.common.collections.ISequence> <ABCInterfaceClass zope.interface.common.collections.ISequence>
<ABCInterfaceClass zope.interface.common.collections.IReversible> <ABCInterfaceClass zope.interface.common.collections.IReversible>
<ABCInterfaceClass zope.interface.common.collections.ICollection> <ABCInterfaceClass zope.interface.common.collections.ICollection>
<ABCInterfaceClass zope.interface.common.collections.ISized> <ABCInterfaceClass zope.interface.common.collections.ISized>
+ <ABCInterfaceClass zope.interface.common.collections.IIterable>
<ABCInterfaceClass zope.interface.common.collections.IContainer> <ABCInterfaceClass zope.interface.common.collections.IContainer>
- <ABCInterfaceClass zope.interface.common.collections.IIterable>
<ABCInterfaceClass zope.interface.common.ABCInterface> <ABCInterfaceClass zope.interface.common.ABCInterface>
+ <implementedBy builtins.object>
<InterfaceClass zope.interface.Interface> <InterfaceClass zope.interface.Interface>
- <implementedBy builtins.object>
Object <ABCInterfaceClass zope.interface.common.mapping.IFullMapping> has different legacy and C3 MROs:
Legacy RO (len=18) C3 RO (len=18; inconsistent=no)
================================================================================================================================================
<ABCInterfaceClass zope.interface.common.mapping.IFullMapping> <ABCInterfaceClass zope.interface.common.mapping.IFullMapping>
<ABCInterfaceClass zope.interface.common.collections.IMutableMapping> <ABCInterfaceClass zope.interface.common.collections.IMutableMapping>
<ABCInterfaceClass zope.interface.common.collections.IMapping> <ABCInterfaceClass zope.interface.common.collections.IMapping>
<ABCInterfaceClass zope.interface.common.collections.ICollection> <ABCInterfaceClass zope.interface.common.collections.ICollection>
- <ABCInterfaceClass zope.interface.common.collections.IIterable>
<InterfaceClass zope.interface.common.mapping.IExtendedReadMapping> <InterfaceClass zope.interface.common.mapping.IExtendedReadMapping>
<InterfaceClass zope.interface.common.mapping.IIterableMapping> <InterfaceClass zope.interface.common.mapping.IIterableMapping>
<InterfaceClass zope.interface.common.mapping.IExtendedWriteMapping> <InterfaceClass zope.interface.common.mapping.IExtendedWriteMapping>
<InterfaceClass zope.interface.common.mapping.IClonableMapping> <InterfaceClass zope.interface.common.mapping.IClonableMapping>
<InterfaceClass zope.interface.common.mapping.IMapping> <InterfaceClass zope.interface.common.mapping.IMapping>
<InterfaceClass zope.interface.common.mapping.IWriteMapping> <InterfaceClass zope.interface.common.mapping.IWriteMapping>
<InterfaceClass zope.interface.common.mapping.IEnumerableMapping> <InterfaceClass zope.interface.common.mapping.IEnumerableMapping>
<ABCInterfaceClass zope.interface.common.collections.ISized> <ABCInterfaceClass zope.interface.common.collections.ISized>
+ <ABCInterfaceClass zope.interface.common.collections.IIterable>
<InterfaceClass zope.interface.common.mapping.IReadMapping> <InterfaceClass zope.interface.common.mapping.IReadMapping>
<ABCInterfaceClass zope.interface.common.collections.IContainer> <ABCInterfaceClass zope.interface.common.collections.IContainer>
<ABCInterfaceClass zope.interface.common.ABCInterface> <ABCInterfaceClass zope.interface.common.ABCInterface>
<InterfaceClass zope.interface.common.mapping.IItemMapping> <InterfaceClass zope.interface.common.mapping.IItemMapping>
<InterfaceClass zope.interface.Interface> <InterfaceClass zope.interface.Interface>
Object <InterfaceClass BTrees.Interfaces.ISet> has different legacy and C3 MROs:
Legacy RO (len=7) C3 RO (len=7; inconsistent=no)
====================================================================================================
<InterfaceClass BTrees.Interfaces.ISet> <InterfaceClass BTrees.Interfaces.ISet>
<InterfaceClass BTrees.Interfaces.IKeySequence> <InterfaceClass BTrees.Interfaces.IKeySequence>
- <InterfaceClass BTrees.Interfaces.ISized>
<InterfaceClass BTrees.Interfaces.ISetMutable> <InterfaceClass BTrees.Interfaces.ISetMutable>
<InterfaceClass BTrees.Interfaces.IKeyed> <InterfaceClass BTrees.Interfaces.IKeyed>
<InterfaceClass BTrees.Interfaces.ICollection> <InterfaceClass BTrees.Interfaces.ICollection>
+ <InterfaceClass BTrees.Interfaces.ISized>
<InterfaceClass zope.interface.Interface> <InterfaceClass zope.interface.Interface>
```
And here's after:
```
Object classImplements(list, IMutableSequence, IIterable) has different legacy and C3 MROs:
Legacy RO (len=11) C3 RO (len=11; inconsistent=no)
==========================================================================================================
classImplements(list, IMutableSequence, IIterable) classImplements(list, IMutableSequence, IIterable)
zope.interface.common.collections.IMutableSequence zope.interface.common.collections.IMutableSequence
zope.interface.common.collections.ISequence zope.interface.common.collections.ISequence
zope.interface.common.collections.IReversible zope.interface.common.collections.IReversible
zope.interface.common.collections.ICollection zope.interface.common.collections.ICollection
zope.interface.common.collections.ISized zope.interface.common.collections.ISized
+ zope.interface.common.collections.IIterable
zope.interface.common.collections.IContainer zope.interface.common.collections.IContainer
- zope.interface.common.collections.IIterable
zope.interface.common.ABCInterface zope.interface.common.ABCInterface
+ classImplements(object)
zope.interface.Interface zope.interface.Interface
- classImplements(object)
Object <ABCInterfaceClass zope.interface.common.mapping.IFullMapping> has different legacy and C3 MROs:
Legacy RO (len=18) C3 RO (len=18; inconsistent=no)
============================================================================================================
zope.interface.common.mapping.IFullMapping zope.interface.common.mapping.IFullMapping
zope.interface.common.collections.IMutableMapping zope.interface.common.collections.IMutableMapping
zope.interface.common.collections.IMapping zope.interface.common.collections.IMapping
zope.interface.common.collections.ICollection zope.interface.common.collections.ICollection
- zope.interface.common.collections.IIterable
zope.interface.common.mapping.IExtendedReadMapping zope.interface.common.mapping.IExtendedReadMapping
zope.interface.common.mapping.IIterableMapping zope.interface.common.mapping.IIterableMapping
zope.interface.common.mapping.IExtendedWriteMapping zope.interface.common.mapping.IExtendedWriteMapping
zope.interface.common.mapping.IClonableMapping zope.interface.common.mapping.IClonableMapping
zope.interface.common.mapping.IMapping zope.interface.common.mapping.IMapping
zope.interface.common.mapping.IWriteMapping zope.interface.common.mapping.IWriteMapping
zope.interface.common.mapping.IEnumerableMapping zope.interface.common.mapping.IEnumerableMapping
zope.interface.common.collections.ISized zope.interface.common.collections.ISized
+ zope.interface.common.collections.IIterable
zope.interface.common.mapping.IReadMapping zope.interface.common.mapping.IReadMapping
zope.interface.common.collections.IContainer zope.interface.common.collections.IContainer
zope.interface.common.ABCInterface zope.interface.common.ABCInterface
zope.interface.common.mapping.IItemMapping zope.interface.common.mapping.IItemMapping
zope.interface.Interface zope.interface.Interface
Object <InterfaceClass BTrees.Interfaces.ISet> has different legacy and C3 MROs:
Legacy RO (len=7) C3 RO (len=7; inconsistent=no)
==================================================================
BTrees.Interfaces.ISet BTrees.Interfaces.ISet
BTrees.Interfaces.IKeySequence BTrees.Interfaces.IKeySequence
- BTrees.Interfaces.ISized
BTrees.Interfaces.ISetMutable BTrees.Interfaces.ISetMutable
BTrees.Interfaces.IKeyed BTrees.Interfaces.IKeyed
BTrees.Interfaces.ICollection BTrees.Interfaces.ICollection
+ BTrees.Interfaces.ISized
zope.interface.Interface zope.interface.Interface
```
2021-03-25 10:30:47 -05:00
686760eb26
Update docs/README.rst: Two expressions need two lines
...
Co-authored-by: Michael Howitz <mh@gocept.com>
2021-03-17 11:42:18 -05:00
488a317abd
Update the Adaptation docs to be more concrete.
...
This should help provide better motivating use cases. Examples inspired by https://glyph.twistedmatrix.com/2021/03/interfaces-and-protocols.html
Also some minor typo fixes and updates to comments.
2021-03-17 07:39:49 -05:00
a8d56b9d3c
Move itertools import to module scope.
...
Also tweak docs.
2021-03-15 06:32:02 -05:00
8a8285133b
Let subclasses of BaseAdapterRegistry customize the data structures.
...
Add extensive tests for this. Fixes #224 .
Also adds test for, and fixes #227
Add BAR.rebuild() to fix the refcount issue, and to change datatypes.
It works by using the new methods allRegistrations() and allSubscriptions() to re-create the data in new data structures.
This makes fresh calls to subscribe() and register(). I went this way instead of trying to manually walk the data structures and create them because the logic in those methods is fully tested.
2021-03-03 05:07:41 -06:00
34085388b3
Add more persistence examples.
2020-10-23 15:32:46 -05:00
2ae267b910
Explore more details of persistence and expand on the motivation for how this relates to equality/hashing/sorting.
2020-10-23 15:18:55 -05:00
27347de877
Add example from #220 to the specification docs and expand it.
2020-10-23 15:18:16 -05:00
4f76a54239
cosmetics
2020-10-19 08:28:18 +02:00
c49e8b27b6
add example
2020-10-19 08:16:55 +02:00
3b99e6d097
Document persistency and equality
2020-10-16 09:28:09 +02:00
8cf31ebd6b
Add info on the interaction of weakrefs and interface hashing.
2020-09-30 10:40:14 -05:00
4cb3e63d3f
Special case the base Interface in @implementer/classImplements to skip the redundancy detection for the sake of plone.app.caching.
2020-04-07 07:32:06 -05:00
46781f87cc
Make @implementer and classImplements not re-declare redundant interfaces.
...
classImplementsOnly and @implementer_only can still be used to do that.
2020-04-07 07:32:06 -05:00
b1807049d4
Feedback from review: whitespace, doc clarification, and a unit test showing the precedence of __conform__ vs __adapt__.
2020-04-07 07:04:44 -05:00
10eadd6305
Let interface 'subclasses' override __adapt__.
...
Cooperate with InterfaceClass to ensure there is no performance penalty for this. Fixes #3
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| Benchmark | bench_master38 | bench_issue3 | bench_issue3_opt |
+=============================================================+================+==============================+==============================+
| call interface (provides; deep) | 369 ns | 454 ns: 1.23x slower (+23%) | not significant |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (provides; wide) | 373 ns | 457 ns: 1.22x slower (+22%) | 365 ns: 1.02x faster (-2%) |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (no alternate, no conform, not provided) | 671 ns | 760 ns: 1.13x slower (+13%) | 636 ns: 1.06x faster (-5%) |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (alternate, no conform, not provided) | 395 ns | 494 ns: 1.25x slower (+25%) | not significant |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (no alternate, valid conform, not provided) | 250 ns | not significant | 227 ns: 1.10x faster (-9%) |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (alternate, invalid conform, not provided) | 348 ns | 424 ns: 1.22x slower (+22%) | not significant |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
2020-04-06 09:14:45 -05:00
1af83ef9f9
Add documentation for taggedValue and invariant.
2020-04-06 09:14:45 -05:00
139bab56a7
Add more cross refs to documentation and fix a couple sphinx warnings about duplicates in the index.
2020-04-06 09:14:45 -05:00
4c4e1c985f
Ensure Interface is the last item in the __sro__.
...
None of the elegant solutions mentioned in the issue worked out, so I had to brute force it.
Fixes #8
2020-03-18 12:06:17 -05:00
bd5a749b5b
Merge pull request #189 from zopefoundation/issue136-issue134
...
Documentation clarifications.
2020-03-18 11:59:47 -05:00
e1e94a0da9
More minor documentation fixups.
...
Mostly formatting. Some interfaces were being documented as clasess, which doesn't work.
2020-03-18 09:55:33 -05:00
f4b777d4a5
Make Interface.getTaggedValue follow the __iro__.
...
Previously it manually walked up __bases__, meaning the answers could be inconsistent.
Fixes #190 .
Also fixes several minor issues in the documentation, mostly cross-reference related.
2020-03-18 07:44:12 -05:00
771721fccf
Documentation clarifications.
...
- docs/adapter.rst
Subscriptions are returned from least to most specific, not the other way around; the docs were incorrect.
Add additional examples, and use more verbose names in current examples, to clarify this. Fixes #136 .
- interfaces.py
names() and namesAndDescriptions() just return a collection, not a sequence. Fixes #134 .
2020-03-17 07:06:54 -05:00
024f643227
Use C3 (mostly) to compute IRO.
...
Fixes #21
The 'mostly' is because interfaces are used in cases that C3 forbids;
when there's a conflict, we fallback to the legacy algorithm. It turns
out there are few conflicts (13K out of 149K total orderings in Plone).
I hoped the fix for #8 might shake out automatically, but it didn't.
Optimize the extremely common case of a __bases__ of length one.
In the benchmark, 4/5 of the interfaces and related objects have a base of length one.
Fix the bad IROs in the bundled ABC interfaces, and implement a way to get warnings or errors.
In running plone/buildout.coredev and tracking the RO requests, the
stats for equal, not equal, and inconsistent-so-fallback, I got
{'ros': 148868, 'eq': 138461, 'ne': 10407, 'inconsistent': 12934}
Add the interface module to the Attribute str.
This was extremely helpful tracking down the Plone problem; IDate is defined in multiple modules.
2020-03-15 09:56:14 -05:00
1e720c3819
Make provided/implementedBy and adapter registries respect super().
...
The query functions now start by looking at the next class in the MRO (interfaces directly provided by the underlying object are not found).
Adapter registries automatically pick up providedBy change to start finding the correct implementations of adapters, but to make that really useful they needed to change to unpack super() arguments and pass __self__ to the factory.
Fixes #11
Unfortunately, this makes PyPy unable to build the C extensions.
Additional crash-safety for adapter lookup.
Make the C functions get the cache only after resolving the
``required`` into a tuple, in case of side-effects like...clearing the
cache. This could lead to the ``cache`` object being deallocated
before we used it.
Drop the ``tuplefy`` function in favor of a direct call to
``PySequence_Tuple``. It's what the ``tuple`` constructor would do
anyway and saves a few steps.
Make sure that getting ``providedBy(super())`` and
``implementedBy(super())`` have no side effects.
2020-03-09 12:51:18 -05:00
d088fd500d
Update documentation and clarify the relationship of the older mapping and sequence interfaces.
2020-02-17 07:02:57 -06:00
a061c2d726
Add interfaces for builtins and the io ABCs.
2020-02-17 07:01:03 -06:00
5cda166377
Add numbers ABC interfaces.
2020-02-17 07:01:03 -06:00
e819c75e60
Add z.i.common.collections to parallel the collections.abc classes.
...
Register implemented standard library types on import.
Derive the interface methods and documentation from the ABC automatically. I hope to use this for numbers too.
Part of #138
2020-02-17 07:01:03 -06:00
e53e797787
Simplify the string formatting rules for the Invalid exceptions.
...
As per review.
Also include the actual failing implementation object in the BrokenMethodImplementation to make it easier to track down what's going on when inheritance is involved.
2020-02-10 08:20:12 -06:00
f6d2e9445d
Make verifyObject/Class collect and raise all errors instead of only the first.
...
Fixes #171 .
2020-02-08 07:57:35 -06:00
83f4f55699
Add warning to change note about string changes breaking doctests.
...
Also tweak documentation to DRY for verifyObject/verifyClass.
2020-02-08 06:21:17 -06:00
e8a4da9d5e
Also document the not-a-method case.
2020-02-07 10:59:11 -06:00
a825e5f29e
Make verification errors more readable and useful.
...
Eliminate the trailing newlines and blank spaces (the code called them
"a stupid artifact").
Include the name of the defining interface (so the user can easily look up
any requirements on the attribute) and, for methods, the expected
signature (no more guessing about how many arguments are required!).
This is implemented by giving Attribute and Method useful reprs and strs.
Previously, they just had the defaults.
Fixes #170
2020-02-07 10:59:11 -06:00
98065287e2
Use .. caution:: to warn about the the old class-advice based APIs
2019-11-11 18:33:31 +02:00
14dad79724
Move the @provider example into the right section
...
Explain that implements()/implementsOnly()/classProvides() not only
should not be "preferred", but are entirely not functional on Python 3.
(These notes should probably use some Sphinx directive to stand out
better, but I'm not well versed in Sphinx and I don't know which one I
should use.)
2019-11-11 18:19:18 +02:00
00b9513ded
Port the documentation examples to Python 3
2019-11-11 15:44:13 +02:00
3042b9fa7c
Update README.ru.rst
...
- Punctuation check and fix.
- Replace some figures of speech.
2019-02-12 08:55:53 +01:00
0146b19bbe
Update README.ru.rst
...
Fixed typo
2019-02-11 14:40:31 +03:00
9014dd0b76
Cross ref from ISpecification to IDeclaration.
2018-07-19 12:16:24 -05:00
bf6228076d
Reorganize the 'declarations' document by functional group.
...
Add cross references and some formatting fixes.
2018-07-19 12:09:08 -05:00
0416521d87
Formatting and cross refs for the 'Interface Specification' doc
2018-07-19 11:25:56 -05:00
e1b905fbf2
Formatting and cross refs for IComponents.
2018-07-19 11:08:35 -05:00
4eb327e585
Basic API reference documentation reorg: split into four functional parts.
...
Add some missing documentation for the events component registries create.
2018-07-19 10:48:55 -05:00
dd50fc30be
Add docstrings with cross-refs to z.i.common.interfaces
...
Also bring the ``classImplements`` lines closer to the interface
declaration. This helped me be sure that nothing was missed and that
all the repetitions of the names matched.
2018-07-19 08:59:07 -05:00
153832496c
Basic automodule directives for the modules in zope.interface.common.
2018-07-19 07:08:51 -05:00
39ca0c5dab
Standarize the ReST headers in api.rst.
2018-07-19 06:54:39 -05:00
Kian-Meng Ang
Michael Howitz
Jason Madden
dieter
Marius Gedminas
Serjio Razin