importlib.resources – Package resource reading, opening and access

Πηγαίος κώδικας: Lib/importlib/resources/__init__.py

---

Νέο στην έκδοση 3.7.

This module leverages Python’s import system to provide access to resources within packages. If you can import a package, you can access resources within that package. Resources can be opened or read, in either binary or text mode.

Οι πόροι είναι κατά κάποιο τρόπο ανάλογοι με αρχεία μέσα σε καταλόγους, αν και είναι σημαντικό να θυμόμαστε ότι αυτή είναι απλώς μια μεταφορά. Οι πόροι και τα πακέτα δεν χρειάζεται να υπάρχουν ως φυσικά αρχεία και κατάλογοι στο σύστημα αρχείων: για παράδειγμα, ένα πακέτο και οι πόροι του μπορούν να εισαχθούν από ένα αρχείο zip χρησιμοποιώντας το zipimport.

Σημείωση

Αυτό το module παρέχει λειτουργικότητα παρόμοια με το pkg_resources Basic Resource Access, χωρίς όμως το κόστος απόδοσης που συνεπάγεται αυτό το πακέτο. Έτσι, η ανάγνωση πόρων που περιλαμβάνονται σε πακέτα γίνεται ευκολότερη, με πιο σταθερή και συνεπή σημασιολογία.

Το αυτόνομο backport αυτού του module παρέχει περισσότερες πληροφορίες στα using importlib.resources και migrating from pkg_resources to importlib.resources.

Οι Loaders που επιθυμούν να υποστηρίξουν ανάγνωση πόρων θα πρέπει να υλοποιήσουν μια μέθοδο get_resource_reader(fullname) όπως ορίζεται από την κλάση importlib.resources.abc.ResourceReader.

class importlib.resources.Package

Όταν μια συνάρτηση δέχεται ένα όρισμα Package, μπορείτε να περάσετε είτε ένα module object είτε όνομα module ως συμβολοσειρά. Μπορείτε να περάσετε μόνο αντικείμενα module των οποίων το __spec__.submodule_search_locations δεν είναι None.

Ο τύπος Package ορίζεται ως Union[str, ModuleType].

importlib.resources.files(package)

Returns a Traversable object representing the resource container for the package (think directory) and its resources (think files). A Traversable may contain other containers (think subdirectories).

package is either a name or a module object which conforms to the Package requirements.

Νέο στην έκδοση 3.9.

importlib.resources.as_file(traversable)

Given a Traversable object representing a file, typically from importlib.resources.files(), return a context manager for use in a with statement. The context manager provides a pathlib.Path object.

Exiting the context manager cleans up any temporary file created when the resource was extracted from e.g. a zip file.

Use as_file when the Traversable methods (read_text, etc) are insufficient and an actual file on the file system is required.

Νέο στην έκδοση 3.9.

Deprecated functions

An older, deprecated set of functions is still available, but is scheduled for removal in a future version of Python. The main drawback of these functions is that they do not support directories: they assume all resources are located directly within a package.

importlib.resources.Resource

Για τα ορίσματα resource στις παρακάτω συναρτήσεις, μπορείτε να περάσετε το όνομα ενός πόρου ως συμβολοσειρά ή ένα path-like object.

Ο τύπος Resource ορίζεται ως Union[str, os.PathLike].

importlib.resources.open_binary(package, resource)

Ανοίγει για δυαδική ανάγνωση το resource μέσα στο package.

Το package είναι είτε όνομα είτε αντικείμενο module που συμμορφώνεται με τις απαιτήσεις της κλάσης Package. Το resource είναι το όνομα του πόρου που θα ανοιχτεί μέσα στο package· δεν μπορεί να περιέχει διαχωριστικά διαδρομών και δεν μπορεί να έχει υπο-πόρους (δηλαδή δεν μπορεί να είναι κατάλογος). Αυτή η συνάρτηση επιστρέφει ένα στιγμιότυπο typing.BinaryIO, δηλαδή ένα δυαδικό ρεύμα εισόδου (binary I/O stream) ανοιχτό για ανάγνωση.

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced by:

files(package).joinpath(resource).open('rb')

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

Ανοίγει για ανάγνωση κειμένου το resource μέσα στο package. Από προεπιλογή, ο πόρος ανοίγει για ανάγνωση ως UTF-8.

Το package είναι είτε ένα όνομα είτε ένα αντικείμενο module που συμμορφώνεται με τις απαιτήσεις της κλάσης Package. Το resource είναι το όνομα του πόρου που θα ανοιχτεί μέσα στο package· δεν μπορεί να περιέχει διαχωριστικά διαδρομών και δεν μπορεί να έχει υπο-πόρους (δηλαδή δεν μπορεί να είναι κατάλογος). Οι παράμετροι encoding και errors έχουν την ίδια σημασία όπως στην ενσωματωμένη open().

Αυτή η συνάρτηση επιστρέφει ένα στιγμιότυπο typing.TextIO, δηλαδή ένα ρεύμα εισόδου κειμένου (text I/O stream) ανοιχτό για ανάγνωση.

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced by:

files(package).joinpath(resource).open('r', encoding=encoding)

importlib.resources.read_binary(package, resource)

Διαβάζει και επιστρέφει τα περιεχόμενα του resource μέσα στο package ως bytes.

Το package είναι είτε ένα όνομα είτε ένα αντικείμενο module που συμμορφώνεται με τις απαιτήσεις της κλάσης Package. Το resource είναι το όνομα του πόρου μέσα στο package· δεν μπορεί να περιέχει διαχωριστικά διαδρομών και δεν μπορεί να έχει υπο-πόρους (δηλαδή δεν μπορεί να είναι κατάλογος). Αυτή η συνάρτηση επιστρέφει τα περιεχόμενα του πόρου ως bytes.

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced by:

files(package).joinpath(resource).read_bytes()

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

Διαβάζει και επιστρέφει τα περιεχόμενα του resource μέσα στο package ως str. Από προεπιλογή, τα περιεχόμενα διαβάζονται ως αυστηρό UTF-8.

Το package είναι είτε όνομα είτε αντικείμενο module που συμμορφώνεται με τις απαιτήσεις της κλάσης Package. Το resource είναι το όνομα του πόρου μέσα στο package· δεν μπορεί να περιέχει διαχωριστικά διαδρομών και δεν μπορεί να έχει υπο-πόρους (δηλαδή δεν μπορεί να είναι κατάλογος). Οι παράμετροι encoding και errors έχουν την ίδια σημασία όπως στην ενσωματωμένη open(). Αυτή η συνάρτηση επιστρέφει τα περιεχόμενα του πόρου ως str.

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced by:

files(package).joinpath(resource).read_text(encoding=encoding)

importlib.resources.path(package, resource)

Επιστρέφει τη διαδρομή του resource ως πραγματική διαδρομή συστήματος αρχείων. Αυτή η συνάρτηση επιστρέφει ένα context manager για χρήση σε μια with πρόταση. Ο context manager παρέχει ένα αντικείμενο pathlib.Path.

Η έξοδος από τον context manager καθαρίζει οποιοδήποτε προσωρινό αρχείο δημιουργήθηκε όταν ο πόρος χρειάστηκε να εξαχθεί, π.χ. από αρχείο zip.

Το package είναι είτε ένα όνομα είτε ένα αντικείμενο module που συμμορφώνεται με τις απαιτήσεις της κλάσης Package. Το resource είναι το όνομα του πόρου μέσα στο package· δεν μπορεί να περιέχει διαχωριστικά διαδρομών και δεν μπορεί να έχει υπο-πόρους (δηλαδή δεν μπορεί να είναι κατάλογος).

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced using as_file():

as_file(files(package).joinpath(resource))

importlib.resources.is_resource(package, name)

Επιστρέφει True αν υπάρχει πόρος με όνομα name στο πακέτο, αλλιώς False. Αυτή η συνάρτηση δεν θεωρεί τους καταλόγους ως πόρους. package είναι είτε όνομα είτε αντικείμενο module που πληροί τις απαιτήσεις Package.

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced by:

files(package).joinpath(resource).is_file()

importlib.resources.contents(package)

Επιστρέφει ένα iterable πάνω στα ονομασμένα στοιχεία μέσα στο πακέτο. Το iterable επιστρέφει πόρους str (π.χ. αρχεία) και μη-πόρους (π.χ. καταλόγους). Το iterable δεν επαναλαμβάνεται σε υποκαταλόγους.

Το package είναι είτε ένα όνομα είτε ένα αντικείμενο module που συμμορφώνεται με τις απαιτήσεις της κλάσης Package.

Αποσύρθηκε στην έκδοση 3.11: Calls to this function can be replaced by:

(resource.name for resource in files(package).iterdir() if resource.is_file())