api.rst 22 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103
  1. :mod:`zope.interface` API Documentation
  2. =======================================
  3. :class:`zope.interface.interface.Specification`
  4. -----------------------------------------------
  5. API
  6. +++
  7. Specification objects implement the API defined by
  8. :class:`zope.interface.interfaces.ISpecification`:
  9. .. autointerface:: zope.interface.interfaces.ISpecification
  10. :members:
  11. :member-order: bysource
  12. Usage
  13. +++++
  14. For example:
  15. .. doctest::
  16. >>> from zope.interface.interface import Specification
  17. >>> from zope.interface import Interface
  18. >>> class I1(Interface):
  19. ... pass
  20. >>> class I2(I1):
  21. ... pass
  22. >>> class I3(I2):
  23. ... pass
  24. >>> [i.__name__ for i in I1.__bases__]
  25. ['Interface']
  26. >>> [i.__name__ for i in I2.__bases__]
  27. ['I1']
  28. >>> I3.extends(I1)
  29. True
  30. >>> I2.__bases__ = (Interface, )
  31. >>> [i.__name__ for i in I2.__bases__]
  32. ['Interface']
  33. >>> I3.extends(I1)
  34. False
  35. Exmples for :meth:`Specification.providedBy`:
  36. .. doctest::
  37. >>> from zope.interface import *
  38. >>> class I1(Interface):
  39. ... pass
  40. >>> class C(object):
  41. ... implements(I1)
  42. >>> c = C()
  43. >>> class X(object):
  44. ... pass
  45. >>> x = X()
  46. >>> I1.providedBy(x)
  47. False
  48. >>> I1.providedBy(C)
  49. False
  50. >>> I1.providedBy(c)
  51. True
  52. >>> directlyProvides(x, I1)
  53. >>> I1.providedBy(x)
  54. True
  55. >>> directlyProvides(C, I1)
  56. >>> I1.providedBy(C)
  57. True
  58. Examples for :meth:`Specification.isOrExtends`:
  59. .. doctest::
  60. >>> from zope.interface import Interface
  61. >>> from zope.interface.declarations import Declaration
  62. >>> class I1(Interface): pass
  63. ...
  64. >>> class I2(I1): pass
  65. ...
  66. >>> class I3(Interface): pass
  67. ...
  68. >>> class I4(I3): pass
  69. ...
  70. >>> spec = Declaration()
  71. >>> int(spec.extends(Interface))
  72. 1
  73. >>> spec = Declaration(I2)
  74. >>> int(spec.extends(Interface))
  75. 1
  76. >>> int(spec.extends(I1))
  77. 1
  78. >>> int(spec.extends(I2))
  79. 1
  80. >>> int(spec.extends(I3))
  81. 0
  82. >>> int(spec.extends(I4))
  83. 0
  84. Examples for :meth:`Specification.interfaces`:
  85. .. doctest::
  86. >>> from zope.interface import Interface
  87. >>> class I1(Interface): pass
  88. ...
  89. >>> class I2(I1): pass
  90. ...
  91. >>> class I3(Interface): pass
  92. ...
  93. >>> class I4(I3): pass
  94. ...
  95. >>> spec = Specification((I2, I3))
  96. >>> spec = Specification((I4, spec))
  97. >>> i = spec.interfaces()
  98. >>> [x.getName() for x in i]
  99. ['I4', 'I2', 'I3']
  100. >>> list(i)
  101. []
  102. Exmples for :meth:`Specification.extends`:
  103. .. doctest::
  104. >>> from zope.interface import Interface
  105. >>> from zope.interface.declarations import Declaration
  106. >>> class I1(Interface): pass
  107. ...
  108. >>> class I2(I1): pass
  109. ...
  110. >>> class I3(Interface): pass
  111. ...
  112. >>> class I4(I3): pass
  113. ...
  114. >>> spec = Declaration()
  115. >>> int(spec.extends(Interface))
  116. 1
  117. >>> spec = Declaration(I2)
  118. >>> int(spec.extends(Interface))
  119. 1
  120. >>> int(spec.extends(I1))
  121. 1
  122. >>> int(spec.extends(I2))
  123. 1
  124. >>> int(spec.extends(I3))
  125. 0
  126. >>> int(spec.extends(I4))
  127. 0
  128. >>> I2.extends(I2)
  129. False
  130. >>> I2.extends(I2, False)
  131. True
  132. >>> I2.extends(I2, strict=False)
  133. True
  134. :class:`zope.interface.interface.InterfaceClass`
  135. ------------------------------------------------
  136. API
  137. +++
  138. Specification objects implement the API defined by
  139. :class:`zope.interface.interfaces.IInterface`:
  140. .. autointerface:: zope.interface.interfaces.IInterface
  141. :members:
  142. :member-order: bysource
  143. Usage
  144. +++++
  145. Exmples for :meth:`InterfaceClass.extends`:
  146. .. doctest::
  147. >>> from zope.interface import Interface
  148. >>> class I1(Interface): pass
  149. ...
  150. >>>
  151. >>> i = I1.interfaces()
  152. >>> [x.getName() for x in i]
  153. ['I1']
  154. >>> list(i)
  155. []
  156. :class:`zope.interface.declarations.Declaration`
  157. ------------------------------------------------
  158. API
  159. +++
  160. Specification objects implement the API defined by
  161. :class:`zope.interface.interfaces.IDeclaration`:
  162. .. autointerface:: zope.interface.interfaces.IDeclaration
  163. :members:
  164. :member-order: bysource
  165. Usage
  166. +++++
  167. Exmples for :meth:`Declaration.__contains__`:
  168. .. doctest::
  169. >>> from zope.interface import Interface
  170. >>> class I1(Interface): pass
  171. ...
  172. >>> class I2(I1): pass
  173. ...
  174. >>> class I3(Interface): pass
  175. ...
  176. >>> class I4(I3): pass
  177. ...
  178. >>> spec = Declaration(I2, I3)
  179. >>> spec = Declaration(I4, spec)
  180. >>> int(I1 in spec)
  181. 0
  182. >>> int(I2 in spec)
  183. 1
  184. >>> int(I3 in spec)
  185. 1
  186. >>> int(I4 in spec)
  187. 1
  188. Exmples for :meth:`Declaration.__iter__`:
  189. .. doctest::
  190. >>> from zope.interface import Interface
  191. >>> class I1(Interface): pass
  192. ...
  193. >>> class I2(I1): pass
  194. ...
  195. >>> class I3(Interface): pass
  196. ...
  197. >>> class I4(I3): pass
  198. ...
  199. >>> spec = Declaration(I2, I3)
  200. >>> spec = Declaration(I4, spec)
  201. >>> i = iter(spec)
  202. >>> [x.getName() for x in i]
  203. ['I4', 'I2', 'I3']
  204. >>> list(i)
  205. []
  206. Exmples for :meth:`Declaration.flattened`:
  207. .. doctest::
  208. >>> from zope.interface import Interface
  209. >>> class I1(Interface): pass
  210. ...
  211. >>> class I2(I1): pass
  212. ...
  213. >>> class I3(Interface): pass
  214. ...
  215. >>> class I4(I3): pass
  216. ...
  217. >>> spec = Declaration(I2, I3)
  218. >>> spec = Declaration(I4, spec)
  219. >>> i = spec.flattened()
  220. >>> [x.getName() for x in i]
  221. ['I4', 'I2', 'I1', 'I3', 'Interface']
  222. >>> list(i)
  223. []
  224. Exmples for :meth:`Declaration.__sub__`:
  225. .. doctest::
  226. >>> from zope.interface import Interface
  227. >>> class I1(Interface): pass
  228. ...
  229. >>> class I2(I1): pass
  230. ...
  231. >>> class I3(Interface): pass
  232. ...
  233. >>> class I4(I3): pass
  234. ...
  235. >>> spec = Declaration()
  236. >>> [iface.getName() for iface in spec]
  237. []
  238. >>> spec -= I1
  239. >>> [iface.getName() for iface in spec]
  240. []
  241. >>> spec -= Declaration(I1, I2)
  242. >>> [iface.getName() for iface in spec]
  243. []
  244. >>> spec = Declaration(I2, I4)
  245. >>> [iface.getName() for iface in spec]
  246. ['I2', 'I4']
  247. >>> [iface.getName() for iface in spec - I4]
  248. ['I2']
  249. >>> [iface.getName() for iface in spec - I1]
  250. ['I4']
  251. >>> [iface.getName() for iface
  252. ... in spec - Declaration(I3, I4)]
  253. ['I2']
  254. Exmples for :meth:`Declaration.__add__`:
  255. .. doctest::
  256. >>> from zope.interface import Interface
  257. >>> class I1(Interface): pass
  258. ...
  259. >>> class I2(I1): pass
  260. ...
  261. >>> class I3(Interface): pass
  262. ...
  263. >>> class I4(I3): pass
  264. ...
  265. >>> spec = Declaration()
  266. >>> [iface.getName() for iface in spec]
  267. []
  268. >>> [iface.getName() for iface in spec+I1]
  269. ['I1']
  270. >>> [iface.getName() for iface in I1+spec]
  271. ['I1']
  272. >>> spec2 = spec
  273. >>> spec += I1
  274. >>> [iface.getName() for iface in spec]
  275. ['I1']
  276. >>> [iface.getName() for iface in spec2]
  277. []
  278. >>> spec2 += Declaration(I3, I4)
  279. >>> [iface.getName() for iface in spec2]
  280. ['I3', 'I4']
  281. >>> [iface.getName() for iface in spec+spec2]
  282. ['I1', 'I3', 'I4']
  283. >>> [iface.getName() for iface in spec2+spec]
  284. ['I3', 'I4', 'I1']
  285. :func:`zope.interface.declarations.implementedBy`
  286. -------------------------------------------------
  287. API
  288. +++
  289. .. autofunction:: zope.interface.declarations.implementedByFallback
  290. Usage
  291. +++++
  292. Consider the following example:
  293. .. doctest::
  294. >>> from zope.interface import Interface
  295. >>> class I1(Interface): pass
  296. ...
  297. >>> class I2(Interface): pass
  298. ...
  299. >>> class I3(Interface): pass
  300. ...
  301. >>> class I4(Interface): pass
  302. ...
  303. >>> class A(object):
  304. ... implements(I3)
  305. >>> class B(object):
  306. ... implements(I4)
  307. >>> class C(A, B):
  308. ... pass
  309. >>> classImplementsOnly(C, I1, I2)
  310. >>> [i.getName() for i in implementedBy(C)]
  311. ['I1', 'I2']
  312. Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
  313. whatever interfaces instances of ``A`` and ``B`` implement.
  314. Another example:
  315. .. doctest::
  316. >>> from zope.interface import Interface
  317. >>> class I1(Interface): pass
  318. ...
  319. >>> class I2(I1): pass
  320. ...
  321. >>> class I3(Interface): pass
  322. ...
  323. >>> class I4(I3): pass
  324. ...
  325. >>> class C1(object):
  326. ... implements(I2)
  327. >>> class C2(C1):
  328. ... implements(I3)
  329. >>> [i.getName() for i in implementedBy(C2)]
  330. ['I3', 'I2']
  331. Really, any object should be able to receive a successful answer, even
  332. an instance:
  333. .. doctest::
  334. >>> class Callable(object):
  335. ... def __call__(self):
  336. ... return self
  337. >>> implementedBy(Callable())
  338. <implementedBy __builtin__.?>
  339. Note that the name of the spec ends with a '?', because the ``Callable``
  340. instance does not have a ``__name__`` attribute.
  341. This also manages storage of implementation specifications.
  342. :func:`zope.interface.declarations.classImplementsOnly`
  343. -------------------------------------------------------
  344. API
  345. +++
  346. .. autofunction:: zope.interface.declarations.classImplementsOnly
  347. Usage
  348. +++++
  349. Consider the following example:
  350. .. doctest::
  351. >>> from zope.interface import Interface
  352. >>> class I1(Interface): pass
  353. ...
  354. >>> class I2(Interface): pass
  355. ...
  356. >>> class I3(Interface): pass
  357. ...
  358. >>> class I4(Interface): pass
  359. ...
  360. >>> class A(object):
  361. ... implements(I3)
  362. >>> class B(object):
  363. ... implements(I4)
  364. >>> class C(A, B):
  365. ... pass
  366. >>> classImplementsOnly(C, I1, I2)
  367. >>> [i.getName() for i in implementedBy(C)]
  368. ['I1', 'I2']
  369. Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
  370. whatever interfaces instances of ``A`` and ``B`` implement.
  371. :func:`zope.interface.declarations.classImplements`
  372. ---------------------------------------------------
  373. API
  374. +++
  375. .. autofunction:: zope.interface.declarations.classImplements
  376. Usage
  377. +++++
  378. Consider the following example:
  379. .. doctest::
  380. >>> from zope.interface import Interface
  381. >>> class I1(Interface): pass
  382. ...
  383. >>> class I2(Interface): pass
  384. ...
  385. >>> class I3(Interface): pass
  386. ...
  387. >>> class I4(Interface): pass
  388. ...
  389. >>> class I5(Interface): pass
  390. ...
  391. >>> class A(object):
  392. ... implements(I3)
  393. >>> class B(object):
  394. ... implements(I4)
  395. >>> class C(A, B):
  396. ... pass
  397. >>> classImplements(C, I1, I2)
  398. >>> [i.getName() for i in implementedBy(C)]
  399. ['I1', 'I2', 'I3', 'I4']
  400. >>> classImplements(C, I5)
  401. >>> [i.getName() for i in implementedBy(C)]
  402. ['I1', 'I2', 'I5', 'I3', 'I4']
  403. Instances of ``C`` provide ``I1``, ``I2``, ``I5``, and whatever
  404. interfaces instances of ``A`` and ``B`` provide.
  405. :class:`zope.interface.declarations.implementer`
  406. ------------------------------------------------
  407. API
  408. +++
  409. .. autoclass:: zope.interface.declarations.implementer
  410. :members:
  411. :member-order: bysource
  412. :class:`zope.interface.declarations.implementer_only`
  413. -----------------------------------------------------
  414. API
  415. +++
  416. .. autoclass:: zope.interface.declarations.implementer_only
  417. :members:
  418. :member-order: bysource
  419. :func:`zope.interface.declarations.implements`
  420. ----------------------------------------------
  421. API
  422. +++
  423. .. autofunction:: zope.interface.declarations.implements
  424. :func:`zope.interface.declarations.implementsOnly`
  425. --------------------------------------------------
  426. API
  427. +++
  428. .. autofunction:: zope.interface.declarations.implementsOnly
  429. :class:`zope.interface.declarations.ProvidesClass`
  430. --------------------------------------------------
  431. API
  432. +++
  433. .. autoclass:: zope.interface.declarations.ProvidesClass
  434. :members:
  435. :member-order: bysource
  436. Usage
  437. +++++
  438. Descriptor semantics (via ``Provides.__get__``):
  439. .. doctest::
  440. >>> from zope.interface import Interface
  441. >>> class IFooFactory(Interface): pass
  442. ...
  443. >>> class C(object):
  444. ... pass
  445. >>> from zope.interface.declarations import ProvidesClass
  446. >>> C.__provides__ = ProvidesClass(C, IFooFactory)
  447. >>> [i.getName() for i in C.__provides__]
  448. ['IFooFactory']
  449. >>> getattr(C(), '__provides__', 0)
  450. 0
  451. :func:`zope.interface.declarations.Provides`
  452. --------------------------------------------------
  453. API
  454. +++
  455. .. autofunction:: zope.interface.declarations.Provides
  456. Usage
  457. +++++
  458. In the examples below, we are going to make assertions about
  459. the size of the weakvalue dictionary. For the assertions to be
  460. meaningful, we need to force garbage collection to make sure garbage
  461. objects are, indeed, removed from the system. Depending on how Python
  462. is run, we may need to make multiple calls to be sure. We provide a
  463. collect function to help with this:
  464. .. doctest::
  465. >>> import gc
  466. >>> def collect():
  467. ... for i in range(4):
  468. ... gc.collect()
  469. >>> collect()
  470. >>> from zope.interface.declarations import InstanceDeclarations
  471. >>> before = len(InstanceDeclarations)
  472. >>> class C(object):
  473. ... pass
  474. >>> from zope.interface import Interface
  475. >>> class I(Interface):
  476. ... pass
  477. >>> c1 = C()
  478. >>> c2 = C()
  479. >>> len(InstanceDeclarations) == before
  480. True
  481. >>> directlyProvides(c1, I)
  482. >>> len(InstanceDeclarations) == before + 1
  483. True
  484. >>> directlyProvides(c2, I)
  485. >>> len(InstanceDeclarations) == before + 1
  486. True
  487. >>> del c1
  488. >>> collect()
  489. >>> len(InstanceDeclarations) == before + 1
  490. True
  491. >>> del c2
  492. >>> collect()
  493. >>> len(InstanceDeclarations) == before
  494. True
  495. :func:`zope.interface.declarations.directlyProvides`
  496. ----------------------------------------------------
  497. API
  498. +++
  499. .. autofunction:: zope.interface.declarations.directlyProvides
  500. Usage
  501. +++++
  502. Consider the following example:
  503. .. doctest::
  504. >>> from zope.interface import Interface
  505. >>> class I1(Interface): pass
  506. ...
  507. >>> class I2(Interface): pass
  508. ...
  509. >>> class IA1(Interface): pass
  510. ...
  511. >>> class IA2(Interface): pass
  512. ...
  513. >>> class IB(Interface): pass
  514. ...
  515. >>> class IC(Interface): pass
  516. ...
  517. >>> class A(object):
  518. ... implements(IA1, IA2)
  519. >>> class B(object):
  520. ... implements(IB)
  521. >>> class C(A, B):
  522. ... implements(IC)
  523. >>> ob = C()
  524. >>> directlyProvides(ob, I1, I2)
  525. >>> int(I1 in providedBy(ob))
  526. 1
  527. >>> int(I2 in providedBy(ob))
  528. 1
  529. >>> int(IA1 in providedBy(ob))
  530. 1
  531. >>> int(IA2 in providedBy(ob))
  532. 1
  533. >>> int(IB in providedBy(ob))
  534. 1
  535. >>> int(IC in providedBy(ob))
  536. 1
  537. The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
  538. instances have been declared for instances of ``C``.
  539. To remove directly provided interfaces, use ``directlyProvidedBy`` and
  540. subtract the unwanted interfaces. For example:
  541. .. doctest::
  542. >>> directlyProvides(ob, directlyProvidedBy(ob)-I2)
  543. >>> int(I1 in providedBy(ob))
  544. 1
  545. >>> int(I2 in providedBy(ob))
  546. 0
  547. removes ``I2`` from the interfaces directly provided by ``ob``. The object,
  548. ``ob`` no longer directly provides ``I2``, although it might still
  549. provide ``I2`` if its class implements ``I2``.
  550. To add directly provided interfaces, use ``directlyProvidedBy`` and
  551. include additional interfaces. For example:
  552. .. doctest::
  553. >>> int(I2 in providedBy(ob))
  554. 0
  555. >>> directlyProvides(ob, directlyProvidedBy(ob), I2)
  556. adds ``I2`` to the interfaces directly provided by ``ob``:
  557. .. doctest::
  558. >>> int(I2 in providedBy(ob))
  559. 1
  560. We need to avoid setting this attribute on meta classes that
  561. don't support descriptors.
  562. We can do away with this check when we get rid of the old EC
  563. :func:`zope.interface.declarations.alsoProvides`
  564. ------------------------------------------------
  565. API
  566. +++
  567. .. autofunction:: zope.interface.declarations.alsoProvides
  568. Usage
  569. +++++
  570. Consider the following example:
  571. .. doctest::
  572. >>> from zope.interface import Interface
  573. >>> class I1(Interface): pass
  574. ...
  575. >>> class I2(Interface): pass
  576. ...
  577. >>> class IA1(Interface): pass
  578. ...
  579. >>> class IA2(Interface): pass
  580. ...
  581. >>> class IB(Interface): pass
  582. ...
  583. >>> class IC(Interface): pass
  584. ...
  585. >>> class A(object):
  586. ... implements(IA1, IA2)
  587. >>> class B(object):
  588. ... implements(IB)
  589. >>> class C(A, B):
  590. ... implements(IC)
  591. >>> ob = C()
  592. >>> directlyProvides(ob, I1)
  593. >>> int(I1 in providedBy(ob))
  594. 1
  595. >>> int(I2 in providedBy(ob))
  596. 0
  597. >>> int(IA1 in providedBy(ob))
  598. 1
  599. >>> int(IA2 in providedBy(ob))
  600. 1
  601. >>> int(IB in providedBy(ob))
  602. 1
  603. >>> int(IC in providedBy(ob))
  604. 1
  605. >>> alsoProvides(ob, I2)
  606. >>> int(I1 in providedBy(ob))
  607. 1
  608. >>> int(I2 in providedBy(ob))
  609. 1
  610. >>> int(IA1 in providedBy(ob))
  611. 1
  612. >>> int(IA2 in providedBy(ob))
  613. 1
  614. >>> int(IB in providedBy(ob))
  615. 1
  616. >>> int(IC in providedBy(ob))
  617. 1
  618. The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
  619. instances have been declared for instances of ``C``. Notice that the
  620. ``alsoProvides`` just extends the provided interfaces.
  621. :func:`zope.interface.declarations.noLongerProvides`
  622. ----------------------------------------------------
  623. API
  624. +++
  625. .. autofunction:: zope.interface.declarations.noLongerProvides
  626. Usage
  627. +++++
  628. Consider the following two interfaces:
  629. .. doctest::
  630. >>> from zope.interface import Interface
  631. >>> class I1(Interface): pass
  632. ...
  633. >>> class I2(Interface): pass
  634. ...
  635. ``I1`` is provided through the class, ``I2`` is directly provided
  636. by the object:
  637. .. doctest::
  638. >>> class C(object):
  639. ... implements(I1)
  640. >>> c = C()
  641. >>> alsoProvides(c, I2)
  642. >>> I2.providedBy(c)
  643. True
  644. Remove ``I2`` from ``c`` again:
  645. .. doctest::
  646. >>> noLongerProvides(c, I2)
  647. >>> I2.providedBy(c)
  648. False
  649. Removing an interface that is provided through the class is not possible:
  650. .. doctest::
  651. >>> noLongerProvides(c, I1)
  652. Traceback (most recent call last):
  653. ...
  654. ValueError: Can only remove directly provided interfaces.
  655. :func:`zope.interface.declarations.directlyProvidedBy`
  656. ------------------------------------------------------
  657. API
  658. +++
  659. .. autofunction:: zope.interface.declarations.directlyProvidedBy
  660. :func:`zope.interface.declarations.classProvides`
  661. -------------------------------------------------
  662. API
  663. +++
  664. .. autofunction:: zope.interface.declarations.classProvides
  665. Usage
  666. +++++
  667. For example:
  668. .. doctest::
  669. >>> from zope.interface import Interface
  670. >>> from zope.interface.declarations import implementer
  671. >>> class IFooFactory(Interface):
  672. ... pass
  673. >>> class IFoo(Interface):
  674. ... pass
  675. >>> @implementer(IFoo)
  676. ... class C(object):
  677. ... classProvides(IFooFactory)
  678. >>> [i.getName() for i in C.__provides__]
  679. ['IFooFactory']
  680. >>> [i.getName() for i in C().__provides__]
  681. ['IFoo']
  682. Which is equivalent to:
  683. .. doctest::
  684. >>> from zope.interface import Interface
  685. >>> class IFoo(Interface): pass
  686. ...
  687. >>> class IFooFactory(Interface): pass
  688. ...
  689. >>> @implementer(IFoo)
  690. ... class C(object):
  691. ... pass
  692. >>> directlyProvides(C, IFooFactory)
  693. >>> [i.getName() for i in C.__providedBy__]
  694. ['IFooFactory']
  695. >>> [i.getName() for i in C().__providedBy__]
  696. ['IFoo']
  697. :class:`zope.interface.declarations.provider`
  698. ---------------------------------------------
  699. API
  700. +++
  701. .. autoclass:: zope.interface.declarations.provider
  702. :members:
  703. :member-order: bysource
  704. :func:`zope.interface.declarations.moduleProvides`
  705. --------------------------------------------------
  706. API
  707. +++
  708. .. autofunction:: zope.interface.declarations.moduleProvides
  709. :func:`zope.interface.declarations.ObjectSpecification`
  710. -------------------------------------------------------
  711. API
  712. +++
  713. .. autofunction:: zope.interface.declarations.ObjectSpecification
  714. Usage
  715. +++++
  716. For example:
  717. .. doctest::
  718. >>> from zope.interface import Interface
  719. >>> class I1(Interface): pass
  720. ...
  721. >>> class I2(Interface): pass
  722. ...
  723. >>> class I3(Interface): pass
  724. ...
  725. >>> class I31(I3): pass
  726. ...
  727. >>> class I4(Interface): pass
  728. ...
  729. >>> class I5(Interface): pass
  730. ...
  731. >>> class A(object):
  732. ... implements(I1)
  733. >>> class B(object): __implemented__ = I2
  734. ...
  735. >>> class C(A, B):
  736. ... implements(I31)
  737. >>> c = C()
  738. >>> directlyProvides(c, I4)
  739. >>> [i.getName() for i in providedBy(c)]
  740. ['I4', 'I31', 'I1', 'I2']
  741. >>> [i.getName() for i in providedBy(c).flattened()]
  742. ['I4', 'I31', 'I3', 'I1', 'I2', 'Interface']
  743. >>> int(I1 in providedBy(c))
  744. 1
  745. >>> int(I3 in providedBy(c))
  746. 0
  747. >>> int(providedBy(c).extends(I3))
  748. 1
  749. >>> int(providedBy(c).extends(I31))
  750. 1
  751. >>> int(providedBy(c).extends(I5))
  752. 0
  753. >>> class COnly(A, B):
  754. ... implementsOnly(I31)
  755. >>> class D(COnly):
  756. ... implements(I5)
  757. >>> c = D()
  758. >>> directlyProvides(c, I4)
  759. >>> [i.getName() for i in providedBy(c)]
  760. ['I4', 'I5', 'I31']
  761. >>> [i.getName() for i in providedBy(c).flattened()]
  762. ['I4', 'I5', 'I31', 'I3', 'Interface']
  763. >>> int(I1 in providedBy(c))
  764. 0
  765. >>> int(I3 in providedBy(c))
  766. 0
  767. >>> int(providedBy(c).extends(I3))
  768. 1
  769. >>> int(providedBy(c).extends(I1))
  770. 0
  771. >>> int(providedBy(c).extends(I31))
  772. 1
  773. >>> int(providedBy(c).extends(I5))
  774. 1
  775. :func:`zope.interface.declarations.providedBy`
  776. ----------------------------------------------
  777. API
  778. +++
  779. .. autofunction:: zope.interface.declarations.providedBy
  780. :class:`zope.interface.declarations.ObjectSpecificationDescriptor`
  781. ------------------------------------------------------------------
  782. API
  783. +++
  784. .. autoclass:: zope.interface.declarations.ObjectSpecificationDescriptor
  785. :members:
  786. :member-order: bysource
  787. Usage
  788. +++++
  789. For example:
  790. .. doctest::
  791. >>> from zope.interface import Interface
  792. >>> class IFoo(Interface): pass
  793. ...
  794. >>> class IFooFactory(Interface): pass
  795. ...
  796. >>> @implementer(IFoo)
  797. ... class C(object):
  798. ... classProvides(IFooFactory)
  799. >>> [i.getName() for i in C.__providedBy__]
  800. ['IFooFactory']
  801. >>> [i.getName() for i in C().__providedBy__]
  802. ['IFoo']
  803. Get an ObjectSpecification bound to either an instance or a class,
  804. depending on how we were accessed.
  805. :class:`zope.interface.declarations.named`
  806. ---------------------------------------------
  807. API
  808. +++
  809. .. autoclass:: zope.interface.declarations.named
  810. :members:
  811. :member-order: bysource
  812. Usage
  813. +++++
  814. For example:
  815. .. doctest::
  816. >>> from zope.interface.declarations import named
  817. >>> @named('foo')
  818. ... class Foo(object):
  819. ... pass
  820. >>> Foo.__component_name__
  821. 'foo'
  822. When registering an adapter or utility component, the registry looks for the
  823. ``__component_name__`` attribute and uses it, if no name was explicitly
  824. provided.
  825. :class:`zope.interface.adapter.AdapterRegistry`
  826. -----------------------------------------------
  827. API
  828. +++
  829. The adapter registry's API is defined by
  830. :class:`zope.interface.interfaces.IAdapterRegistry`:
  831. .. autointerface:: zope.interface.adapter.IAdapterRegistry
  832. :members:
  833. :member-order: bysource
  834. Usage
  835. +++++
  836. See :ref:`adapter-registry`.
  837. ``zope.interface.registry.Components``
  838. --------------------------------------
  839. API
  840. +++
  841. The component registry's API is defined by
  842. ``zope.interface.interfaces.IComponents``:
  843. .. autointerface:: zope.interface.interfaces.IComponents
  844. :members:
  845. :member-order: bysource
  846. .. autointerface:: zope.interface.interfaces.IComponentLookup
  847. :members:
  848. :member-order: bysource
  849. .. autointerface:: zope.interface.interfaces.IComponentRegistry
  850. :members:
  851. :member-order: bysource