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

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

Added in version 3.7.

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

«Resources» are file-like resources associated with a module or package in Python. The resources may be contained directly in a package, within a subdirectory contained in that package, or adjacent to modules outside a package. Resources may be text or binary. As a result, a package’s Python module sources (.py), compilation artifacts (pycache), and installation artifacts (like reserved filenames in directories) are technically de-facto resources of that package. In practice, however, resources are primarily those non-Python artifacts exposed specifically by the package author.

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

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

Ένα σύνολο απλοποιημένων, βοηθών συμβατών με προηγούμενες εκδόσεις είναι διαθέσιμο. Αυτά επιτρέπουν κοινές λειτουργίες σε μια κλήση συνάρτησης.

Για όλες τις παρακάτω λειτουργίες:

  • Το anchor είναι μια Anchor, όπως στη files(). Σε αντίθεση με τα αρχεία, ενδέχεται να μην παραλειφθεί.

  • Τα path_names είναι στοιχεία του ονόματος διαδρομής ενός πόρου, σε σχέση με το anchor. Για παράδειγμα, για να λάβετε το κείμενο του πόρου με το όνομα info.txt, χρησιμοποιήστε:

    importlib.resources.read_text(my_module, "info.txt")

    Όπως Traversable.joinpath, Τα μεμονωμένα στοιχεία θα πρέπει να χρησιμοποιούν κάθετε (/) ως διαχωριστές διαδρομή. Για παράδειγμα, τα ακόλουθα είναι ισοδύναμα:

    importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")

    Για λόγους συμβατότητας προς τα πίσω, οι συναρτήσεις που διαβάζουν κείμενο απαιτούν ένα ρητό όρισμα encoding εάν δίνονται πολλά path_names. Για παράδειγμα, για να λάβετε το κείμενο του info/chapter1.txt, χρησιμοποιήστε:

    importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
importlib.resources.open_binary(anchor, *path_names)

Ανοίξτε τον πόρο με όνομα για δυαδική ανάγνωση.

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και path_names.

Αυτή η συνάρτηση επιστρέφει ένα αντικείμενο BinaryIO, ένα δυαδικό ρεύμα εισόδου για ανάγνωση.

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

files(anchor).joinpath(*path_names).open('rb')

Άλλαξε στην έκδοση 3.13: Γίνονται αποδεκτά πολλά path_names.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

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

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και το path_names. Τα encoding και errors έχουν την ίδια σημασία όπως στο ενσωματωμένο open().

Για λόγους συμβατότητας για προηγούμενες εκδόσεις, το όρισμα encoding πρέπει να δίνεται ρητά εάν υπάρχουν πολλά path_names. Αυτό ο περιορισμός έχει προγραμματιστεί να καταργηθεί στην Python 3.15.

Αυτή η συνάρτηση επιστρέφει ένα TextIO αντικείμενο, δηλαδή ένα ρεύμα εισόδου για ανάγνωση.

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

files(anchor).joinpath(*path_names).open('r', encoding=encoding)

Άλλαξε στην έκδοση 3.13: Πολλαπλά path_names γίνονται δεκτά. Τα encoding και errors πρέπει να δίνονται ως ορίσματα λέξεων-κλειδιών.

importlib.resources.read_binary(anchor, *path_names)

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

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και path_names.

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

files(anchor).joinpath(*path_names).read_bytes()

Άλλαξε στην έκδοση 3.13: Γίνονται αποδεκτά πολλά path_names.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

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

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και το path_names. Τα encoding και errors έχουν την ίδια σημασία όπως στο ενσωματωμένο open().

Για λόγους συμβατότητας για προηγούμενες εκδόσεις, το όρισμα encoding πρέπει να δίνεται ρητά εάν υπάρχουν πολλά path_names. Αυτό ο περιορισμός έχει προγραμματιστεί να καταργηθεί στην Python 3.15.

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

files(anchor).joinpath(*path_names).read_text(encoding=encoding)

Άλλαξε στην έκδοση 3.13: Πολλαπλά path_names γίνονται δεκτά. Τα encoding και errors πρέπει να δίνονται ως ορίσματα λέξεων-κλειδιών.

importlib.resources.path(anchor, *path_names)

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

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

Για παράδειγμα, η μέθοδος stat() απαιτεί μια πραγματική διαδρομή συστήματος αρχείων· μπορεί να χρησιμοποιηθεί ως εξής:

with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και path_names.

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

as_file(files(anchor).joinpath(*path_names))

Άλλαξε στην έκδοση 3.13: Πολλαπλά path_names γίνονται δεκτά. Τα encoding και errors πρέπει να δίνονται ως ορίσματα λέξεων-κλειδιών.

importlib.resources.is_resource(anchor, *path_names)

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

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και path_names.

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

files(anchor).joinpath(*path_names).is_file()

Άλλαξε στην έκδοση 3.13: Γίνονται αποδεκτά πολλά path_names.

importlib.resources.contents(anchor, *path_names)

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

Δείτε the introduction για λεπτομέρειες σχετικά με το anchor και path_names.

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

for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name

Αποσύρθηκε στην έκδοση 3.11: Προτιμήστε το iterdir() όπως παραπάνω, το οποίο προσφέρει περισσότερο έλεγχο στα αποτελέσματα και πιο πλούσια λειτουργικότητα.