importlib.resources – Ανάγνωση, άνοιγμα και πρόσβαση σε πόρους πακέτων

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

---

Added in version 3.7.

Αυτό το module αξιοποιεί το σύστημα εισαγωγής της Python για να παρέχει πρόσβαση σε πόρους εντός πακέτων.

«Πόροι» είναι πόροι που μοιάζουν με αρχεία και σχετίζονται με ένα module ή πακέτο στην Python. Οι πόροι μπορεί να περιέχονται απευθείας σε ένα πακέτο, μέσα σε έναν υποκατάλογο που περιλαμβάνεται σε αυτό το πακέτο, ή δίπλα σε modules έξω από ένα πακέτο. Οι πόροι μπορεί να είναι μορφής κειμένου ή δυαδικής μορφής. Ως αποτέλεσμα, ο πηγαίος κώδικας των modules της Python (.py) ενός πακέτου και τα αποτελέσματα μεταγλώττισης (pycache) είναι τεχνικά de-facto πόροι αυτού του πακέτου. Ωστόσο, στην πράξη, οι πόροι είναι κυρίως εκείνα τα μη-Python αρχεία που εκτίθενται συγκεκριμένα από τον συγγραφέα του πακέτου.

Οι πόροι μπορούν να ανοίξουν ή να διαβαστούν είτε σε δυαδική κατάσταση είτε σε κατάσταση κειμένου.

Οι πόροι είναι κατά κάποιο τρόπο ανάλογοι με αρχεία μέσα σε καταλόγους, αν και είναι σημαντικό να θυμόμαστε ότι αυτή είναι απλώς μια μεταφορά. Οι πόροι και τα πακέτα δεν χρειάζεται να υπάρχουν ως φυσικά αρχεία και κατάλογοι στο σύστημα αρχείων: για παράδειγμα, ένα πακέτο και οι πόροι του μπορούν να εισαχθούν από ένα αρχείο 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.Anchor

Αντιπροσωπεύει μία άγκυρα (anchor) για πόρους, είτε ένα module object είτε ένα όνομα module ως συμβολοσειρά. Ορίζεται ως Union[str, ModuleType].

importlib.resources.files(anchor: Anchor | None = None)

Επιστρέφει ένα αντικείμενο Traversable που αντιπροσωπεύει το δοχείο των πόρων (σκεφτείτε έναν κατάλογο) και τους πόρους του (σκεφτείτε αρχεία). Ένα Traversable μπορεί να περιέχει και άλλα δοχεία (σκεφτείτε υποκαταλόγους).

Το anchor είναι μια προαιρετική κλάση Anchor. Αν το anchor είναι πακέτο, οι πόροι επιλύονται σε αυτό το πακέτο. Αν είναι module, οι πόροι επιλύονται δίπλα σε αυτό το module (στο ίδιο πακέτο ή στη ρίζα του πακέτου). Αν το anchor παραλειφθεί, χρησιμοποιείται το module του καλούντος.

Added in version 3.9.

Άλλαξε στην έκδοση 3.12: Η παράμετρος package μετονομάστηκε σε anchor. Το anchor μπορεί πλέον να είναι ένα module που δεν είναι πακέτο και αν παραλειφθεί θα χρησιμοποιηθεί το module του καλούντος. Το package γίνεται ακόμα αποδεκτό για συμβατότητα αλλά θα εμφανίσει ένα DeprecationWarning.Σκεφτείτε να περάσετε το anchor ως positional όρισμα ή να χρησιμοποιήσετε το importlib_resources >= 5.10 για συμβατή διεπαφή σε παλαιότερες εκδόσεις Python.

importlib.resources.as_file(traversable)

Δεδομένου ενός αντικειμένου Traversable που αντιπροσωπεύει ένα αρχείο ή κατάλογο, συνήθως από το importlib.resources.files(), επιστρέφει ένα context manager για χρήση σε μια with πρόταση. Ο context manager παρέχει ένα αντικείμενο pathlib.Path.

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

Χρησιμοποιήστε το as_file όταν οι μέθοδοι του Traversable (όπως read_text, κλπ) δεν επαρκούν και απαιτείται ένα πραγματικό αρχείο ή κατάλογος στο σύστημα αρχείων.

Added in version 3.9.

Άλλαξε στην έκδοση 3.12: Προστέθηκε υποστήριξη για traversable που αντιπροσωπεύει έναν κατάλογο.

Λειτουργικό API

Μια παλαιότερη, απαρχαιωμένη σειρά συναρτήσεων εξακολουθεί να είναι διαθέσιμη. Το κύριο μειονέκτημα αυτών των συναρτήσεων είναι ότι δεν υποστηρίζουν καταλόγους: υποθέτουν ότι όλοι οι πόροι βρίσκονται απευθείας μέσα σε ένα package.

importlib.resources.Package

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

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

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) ανοιχτό για ανάγνωση.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

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) ανοιχτό για ανάγνωση.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

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

importlib.resources.read_binary(package, resource)

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

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

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

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.

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

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· δεν μπορεί να περιέχει διαχωριστικά διαδρομών και δεν μπορεί να έχει υπο-πόρους (δηλαδή δεν μπορεί να είναι κατάλογος).

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με

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

importlib.resources.is_resource(package, name)

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

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

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

importlib.resources.contents(package)

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

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

Αυτή η συνάρτηση είναι περίπου ισοδύναμη με:

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