| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
1 parent a4086d7 commit ef016f5
6 files changed
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -596,172 +596,6 @@ ABC hierarchy:: | |||
| 596 | 596 | itself does not end in ``__init__``. | |
| 597 | 597 | ||
| 598 | 598 | ||
| 599 | - .. class:: ResourceReader | ||
| 600 | - | ||
| 601 | - *Superseded by TraversableResources* | ||
| 602 | - | ||
| 603 | - An :term:`abstract base class` to provide the ability to read | ||
| 604 | - *resources*. | ||
| 605 | - | ||
| 606 | - From the perspective of this ABC, a *resource* is a binary | ||
| 607 | - artifact that is shipped within a package. Typically this is | ||
| 608 | - something like a data file that lives next to the ``__init__.py`` | ||
| 609 | - file of the package. The purpose of this class is to help abstract | ||
| 610 | - out the accessing of such data files so that it does not matter if | ||
| 611 | - the package and its data file(s) are stored e.g. in a zip file | ||
| 612 | - versus on the file system. | ||
| 613 | - | ||
| 614 | - For any of methods of this class, a *resource* argument is | ||
| 615 | - expected to be a :term:`path-like object` which represents | ||
| 616 | - conceptually just a file name. This means that no subdirectory | ||
| 617 | - paths should be included in the *resource* argument. This is | ||
| 618 | - because the location of the package the reader is for, acts as the | ||
| 619 | - "directory". Hence the metaphor for directories and file | ||
| 620 | - names is packages and resources, respectively. This is also why | ||
| 621 | - instances of this class are expected to directly correlate to | ||
| 622 | - a specific package (instead of potentially representing multiple | ||
| 623 | - packages or a module). | ||
| 624 | - | ||
| 625 | - Loaders that wish to support resource reading are expected to | ||
| 626 | - provide a method called ``get_resource_reader(fullname)`` which | ||
| 627 | - returns an object implementing this ABC's interface. If the module | ||
| 628 | - specified by fullname is not a package, this method should return | ||
| 629 | - :const:`None`. An object compatible with this ABC should only be | ||
| 630 | - returned when the specified module is a package. | ||
| 631 | - | ||
| 632 | - .. versionadded:: 3.7 | ||
| 633 | - | ||
| 634 | - .. deprecated-removed:: 3.12 3.14 | ||
| 635 | - Use :class:`importlib.resources.abc.TraversableResources` instead. | ||
| 636 | - | ||
| 637 | - .. method:: open_resource(resource) | ||
| 638 | - :abstractmethod: | ||
| 639 | - | ||
| 640 | - Returns an opened, :term:`file-like object` for binary reading | ||
| 641 | - of the *resource*. | ||
| 642 | - | ||
| 643 | - If the resource cannot be found, :exc:`FileNotFoundError` is | ||
| 644 | - raised. | ||
| 645 | - | ||
| 646 | - .. method:: resource_path(resource) | ||
| 647 | - :abstractmethod: | ||
| 648 | - | ||
| 649 | - Returns the file system path to the *resource*. | ||
| 650 | - | ||
| 651 | - If the resource does not concretely exist on the file system, | ||
| 652 | - raise :exc:`FileNotFoundError`. | ||
| 653 | - | ||
| 654 | - .. method:: is_resource(name) | ||
| 655 | - :abstractmethod: | ||
| 656 | - | ||
| 657 | - Returns ``True`` if the named *name* is considered a resource. | ||
| 658 | - :exc:`FileNotFoundError` is raised if *name* does not exist. | ||
| 659 | - | ||
| 660 | - .. method:: contents() | ||
| 661 | - :abstractmethod: | ||
| 662 | - | ||
| 663 | - Returns an :term:`iterable` of strings over the contents of | ||
| 664 | - the package. Do note that it is not required that all names | ||
| 665 | - returned by the iterator be actual resources, e.g. it is | ||
| 666 | - acceptable to return names for which :meth:`is_resource` would | ||
| 667 | - be false. | ||
| 668 | - | ||
| 669 | - Allowing non-resource names to be returned is to allow for | ||
| 670 | - situations where how a package and its resources are stored | ||
| 671 | - are known a priori and the non-resource names would be useful. | ||
| 672 | - For instance, returning subdirectory names is allowed so that | ||
| 673 | - when it is known that the package and resources are stored on | ||
| 674 | - the file system then those subdirectory names can be used | ||
| 675 | - directly. | ||
| 676 | - | ||
| 677 | - The abstract method returns an iterable of no items. | ||
| 678 | - | ||
| 679 | - | ||
| 680 | - .. class:: Traversable | ||
| 681 | - | ||
| 682 | - An object with a subset of :class:`pathlib.Path` methods suitable for | ||
| 683 | - traversing directories and opening files. | ||
| 684 | - | ||
| 685 | - For a representation of the object on the file-system, use | ||
| 686 | - :meth:`importlib.resources.as_file`. | ||
| 687 | - | ||
| 688 | - .. versionadded:: 3.9 | ||
| 689 | - | ||
| 690 | - .. deprecated-removed:: 3.12 3.14 | ||
| 691 | - Use :class:`importlib.resources.abc.Traversable` instead. | ||
| 692 | - | ||
| 693 | - .. attribute:: name | ||
| 694 | - | ||
| 695 | - Abstract. The base name of this object without any parent references. | ||
| 696 | - | ||
| 697 | - .. method:: iterdir() | ||
| 698 | - :abstractmethod: | ||
| 699 | - | ||
| 700 | - Yield ``Traversable`` objects in ``self``. | ||
| 701 | - | ||
| 702 | - .. method:: is_dir() | ||
| 703 | - :abstractmethod: | ||
| 704 | - | ||
| 705 | - Return ``True`` if ``self`` is a directory. | ||
| 706 | - | ||
| 707 | - .. method:: is_file() | ||
| 708 | - :abstractmethod: | ||
| 709 | - | ||
| 710 | - Return ``True`` if ``self`` is a file. | ||
| 711 | - | ||
| 712 | - .. method:: joinpath(child) | ||
| 713 | - :abstractmethod: | ||
| 714 | - | ||
| 715 | - Return Traversable child in ``self``. | ||
| 716 | - | ||
| 717 | - .. method:: __truediv__(child) | ||
| 718 | - :abstractmethod: | ||
| 719 | - | ||
| 720 | - Return ``Traversable`` child in ``self``. | ||
| 721 | - | ||
| 722 | - .. method:: open(mode='r', *args, **kwargs) | ||
| 723 | - :abstractmethod: | ||
| 724 | - | ||
| 725 | - *mode* may be 'r' or 'rb' to open as text or binary. Return a handle | ||
| 726 | - suitable for reading (same as :attr:`pathlib.Path.open`). | ||
| 727 | - | ||
| 728 | - When opening as text, accepts encoding parameters such as those | ||
| 729 | - accepted by :class:`io.TextIOWrapper`. | ||
| 730 | - | ||
| 731 | - .. method:: read_bytes() | ||
| 732 | - | ||
| 733 | - Read contents of ``self`` as bytes. | ||
| 734 | - | ||
| 735 | - .. method:: read_text(encoding=None) | ||
| 736 | - | ||
| 737 | - Read contents of ``self`` as text. | ||
| 738 | - | ||
| 739 | - | ||
| 740 | - .. class:: TraversableResources | ||
| 741 | - | ||
| 742 | - An abstract base class for resource readers capable of serving | ||
| 743 | - the :meth:`importlib.resources.files` interface. Subclasses | ||
| 744 | - :class:`importlib.resources.abc.ResourceReader` and provides | ||
| 745 | - concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s | ||
| 746 | - abstract methods. Therefore, any loader supplying | ||
| 747 | - :class:`importlib.abc.TraversableResources` also supplies ResourceReader. | ||
| 748 | - | ||
| 749 | - Loaders that wish to support resource reading are expected to | ||
| 750 | - implement this interface. | ||
| 751 | - | ||
| 752 | - .. versionadded:: 3.9 | ||
| 753 | - | ||
| 754 | - .. deprecated-removed:: 3.12 3.14 | ||
| 755 | - Use :class:`importlib.resources.abc.TraversableResources` instead. | ||
| 756 | - | ||
| 757 | - .. method:: files() | ||
| 758 | - :abstractmethod: | ||
| 759 | - | ||
| 760 | - Returns a :class:`importlib.resources.abc.Traversable` object for the loaded | ||
| 761 | - package. | ||
| 762 | - | ||
| 763 | - | ||
| 764 | - | ||
| 765 | 599 | :mod:`importlib.machinery` -- Importers and path hooks | |
| 766 | 600 | ------------------------------------------------------ | |
| 767 | 601 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -604,7 +604,7 @@ new ABC for access to, opening, and reading *resources* inside packages. | |||
| 604 | 604 | Resources are roughly similar to files inside packages, but they needn't | |
| 605 | 605 | be actual files on the physical file system. Module loaders can provide a | |
| 606 | 606 | :meth:`!get_resource_reader` function which returns | |
| 607 | - a :class:`importlib.abc.ResourceReader` instance to support this | ||
| 607 | + a :class:`!importlib.abc.ResourceReader` instance to support this | ||
| 608 | 608 | new API. Built-in file path loaders and zip file loaders both support this. | |
| 609 | 609 | ||
| 610 | 610 | Contributed by Barry Warsaw and Brett Cannon in :issue:`32248`. | |
@@ -1043,7 +1043,7 @@ window are shown and hidden in the Options menu. | |||
| 1043 | 1043 | importlib | |
| 1044 | 1044 | --------- | |
| 1045 | 1045 | ||
| 1046 | - The :class:`importlib.abc.ResourceReader` ABC was introduced to | ||
| 1046 | + The :class:`!importlib.abc.ResourceReader` ABC was introduced to | ||
| 1047 | 1047 | support the loading of resources from packages. See also | |
| 1048 | 1048 | :ref:`whatsnew37_importlib_resources`. | |
| 1049 | 1049 | (Contributed by Barry Warsaw, Brett Cannon in :issue:`32248`.) | |
@@ -2032,7 +2032,7 @@ both deprecated in Python 3.4 now emit :exc:`DeprecationWarning`. | |||
| 2032 | 2032 | (Contributed by Matthias Bussonnier in :issue:`29576`.) | |
| 2033 | 2033 | ||
| 2034 | 2034 | The :class:`importlib.abc.ResourceLoader` ABC has been deprecated in | |
| 2035 | - favour of :class:`importlib.abc.ResourceReader`. | ||
| 2035 | + favour of :class:`!importlib.abc.ResourceReader`. | ||
| 2036 | 2036 | ||
| 2037 | 2037 | ||
| 2038 | 2038 | locale | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -403,7 +403,7 @@ SOCK_CLOEXEC. | |||
| 403 | 403 | .. nonce: zmO8G2 | |
| 404 | 404 | .. section: Library | |
| 405 | 405 | ||
| 406 | - Add :class:`importlib.abc.ResourceReader` as an ABC for loaders to provide a | ||
| 406 | + Add :class:`!importlib.abc.ResourceReader` as an ABC for loaders to provide a | ||
| 407 | 407 | unified API for reading resources contained within packages. Also add | |
| 408 | 408 | :mod:`importlib.resources` as the port of ``importlib_resources``. | |
| 409 | 409 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -598,7 +598,7 @@ Add socket.getblocking() method. | |||
| 598 | 598 | .. nonce: zmO8G2 | |
| 599 | 599 | .. section: Library | |
| 600 | 600 | ||
| 601 | - Add :mod:`importlib.resources` and :class:`importlib.abc.ResourceReader` as | ||
| 601 | + Add :mod:`importlib.resources` and :class:`!importlib.abc.ResourceReader` as | ||
| 602 | 602 | the unified API for reading resources contained within packages. Loaders | |
| 603 | 603 | wishing to support resource reading must implement the | |
| 604 | 604 | :meth:`get_resource_reader` method. File-based and zipimport-based | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -152,7 +152,7 @@ Ensure line-endings are respected when using lib2to3. | |||
| 152 | 152 | .. section: Library | |
| 153 | 153 | ||
| 154 | 154 | Have :func:`importlib.resources.contents` and | |
| 155 | - :meth:`importlib.abc.ResourceReader.contents` return an :term:`iterable` | ||
| 155 | + :meth:`!importlib.abc.ResourceReader.contents` return an :term:`iterable` | ||
| 156 | 156 | instead of an :term:`iterator`. | |
| 157 | 157 | ||
| 158 | 158 | .. | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -5130,7 +5130,7 @@ Ensure line-endings are respected when using lib2to3. | |||
| 5130 | 5130 | .. section: Library | |
| 5131 | 5131 | ||
| 5132 | 5132 | Have :func:`importlib.resources.contents` and | |
| 5133 | - :meth:`importlib.abc.ResourceReader.contents` return an :term:`iterable` | ||
| 5133 | + :meth:`!importlib.abc.ResourceReader.contents` return an :term:`iterable` | ||
| 5134 | 5134 | instead of an :term:`iterator`. | |
| 5135 | 5135 | ||
| 5136 | 5136 | .. | |
| Back | FazBrowse Home | New Git URL |
0 commit comments