# `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())