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

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

======================================================================

Added in version 3.7.

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

"Πόροι" είναι πόροι που μοιάζουν με αρχεία και σχετίζονται με ένα
module ή πακέτο στην Python. Οι πόροι μπορεί να περιέχονται απευθείας
σε ένα πακέτο, μέσα σε έναν υποκατάλογο που περιλαμβάνεται σε αυτό το
πακέτο, ή δίπλα σε modules έξω από ένα πακέτο. Οι πόροι μπορεί να
είναι μορφής κειμένου ή δυαδικής μορφής. Ως αποτέλεσμα, ο πηγαίος
κώδικας των modules της Python (.py) ενός πακέτου και τα αποτελέσματα
μεταγλώττισης (pycache) και τα αποτελέσματα εγκατάστασης (όπως
"reserved filenames" σε καταλόγους) είναι τεχνικά 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
===============

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

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

* Το *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()" όπως
   παραπάνω, το οποίο προσφέρει περισσότερο έλεγχο στα αποτελέσματα
   και πιο πλούσια λειτουργικότητα.
