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_resourcesBasic Resource Access, χωρίς όμως το κόστος απόδοσης που συνεπάγεται αυτό το πακέτο. Έτσι, η ανάγνωση πόρων που περιλαμβάνονται σε πακέτα γίνεται ευκολότερη, με πιο σταθερή και συνεπή σημασιολογία.

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

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

classimportlib.resources.Anchor

Αντιπροσωπεύει μία άγκυρα (anchor) για πόρους, είτε έναmoduleobject είτε ένα όνομα 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, μπορείτε να περάσετε είτε έναmoduleobject είτε όνομα module ως συμβολοσειρά. Μπορείτε να περάσετε μόνο αντικείμενα module των οποίων το__spec__.submodule_search_locations δεν είναιNone.

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

importlib.resources.Resource

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

Ο τύπος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.nameforresourceinfiles(package).iterdir()ifresource.is_file())