"zipapp" --- Διαχείριση εκτελέσιμων αρχείων zip Python
******************************************************

Added in version 3.5.

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

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

Το παρόν module παρέχει εργαλεία για τη διαχείριση της δημιουργίας
αρχείων zip που περιέχουν κώδικα Python, τα οποία μπορούν να executed
directly by the Python interpreter. Το module παρέχει τόσο μια Διεπαφή
Γραμμής Εντολών όσο και ένα  Διεπαφή Python.


Βασικό Παράδειγμα
=================

Το παρακάτω παράδειγμα δείχνει πώς μπορεί να χρησιμοποιηθεί η Διεπαφή
Γραμμής Εντολών για να δημιουργήσει ένα εκτελέσιμο αρχείο από έναν
φάκελο που περιέχει κώδικα Python. Όταν εκτελείται, το αρχείο θα
εκτελέσει τη συνάρτηση "main" από το module "myapp" στο αρχείο.

   $ python -m zipapp myapp -m "myapp:main"
   $ python myapp.pyz
   <output from myapp>


Διεπαφή Γραμμής Εντολών
=======================

Όταν καλείται ως πρόγραμμα από τη γραμμή εντολών, χρησιμοποιείται η
παρακάτω μορφή:

   $ python -m zipapp source [options]

Αν το *source* είναι ένας φάκελος, αυτό θα δημιουργήσει ένα αρχείο από
τα περιεχόμενα του *source*. Αν το *source* είναι ένα αρχείο, θα
πρέπει να είναι ένα αρχείο, και θα αντιγραφεί στο αρχείο προορισμού (ή
το περιεχόμενο της γραμμής shebang θα εμφανιστεί αν έχει καθοριστεί η
επιλογή --info).

Οι παρακάτω επιλογές γίνονται κατανοητές:

-o <output>, --output=<output>

   Γράφει την έξοδο σε ένα αρχείο με όνομα *output*. Αν αυτή η επιλογή
   δεν καθοριστεί, το όνομα του αρχείου εξόδου θα είναι το ίδιο με το
   εισαγωγικό *source*, με την προσθήκη της επέκτασης ".pyz". Αν
   καθοριστεί ένα ρητό όνομα αρχείου, χρησιμοποιείται όπως είναι (έτσι
   θα πρέπει να συμπεριληφθεί μια επέκταση ".pyz" αν απαιτείται).

   Ένα όνομα αρχείου εξόδου πρέπει να καθοριστεί αν το *source* είναι
   ένα αρχείο (και σε αυτή την περίπτωση, το *output* δεν πρέπει να
   είναι το ίδιο με το *source*).

-p <interpreter>, --python=<interpreter>

   Προσθέτει μια γραμμή "#!" στο αρχείο που καθορίζει το *interpreter*
   ως την εντολή που θα εκτελεστεί. Επίσης, σε POSIX, καθιστά το
   αρχείο εκτελέσιμο. Η προεπιλογή είναι να μην γράφεται καμία γραμμή
   "#!" και να μην καθίσταται το αρχείο εκτελέσιμο.

-m <mainfn>, --main=<mainfn>

   Γράφει ένα αρχείο "__main__.py" στο αρχείο που εκτελεί το *mainfn*.
   Το *mainfn* πρέπει να έχει τη μορφή "pkg.mod:fn", όπου "pkg.mod"
   είναι ένα πακέτο/module στο αρχείο, και "fn" είναι μια καλούμενη
   συνάρτηση στο δεδομένο module. Το αρχείο "__main__.py" θα εκτελέσει
   αυτή τη συνάρτηση.

   Η επιλογή "--main" δεν μπορεί να καθοριστεί κατά την αντιγραφή ενός
   αρχείου.

-c, --compress

   Συμπιέζει τα αρχεία με τη μέθοδο deflate, μειώνοντας το μέγεθος του
   αρχείου εξόδου. Από προεπιλογή, τα αρχεία αποθηκεύονται χωρίς
   συμπίεση στο αρχείο.

   Η επιλογή "--compress" δεν έχει καμία επίδραση κατά την αντιγραφή
   ενός αρχείου.

   Added in version 3.7.

--info

   Εμφανίζει τον ενσωματωμένο διερμηνέα στο αρχείο, για διαγνωστικούς
   σκοπούς. Σε αυτή την περίπτωση, αγνοούνται όλες οι άλλες επιλογές
   και το SOURCE πρέπει να είναι ένα αρχείο, όχι ένας φάκελος.

-h, --help

   Εκτυπώνει ένα σύντομο μήνυμα χρήσης και εξέρχεται.


Διεπαφή Python
==============

Το module ορίζει δύο συναρτήσεις ευκολίας:

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)

   Δημιουργεί ένα αρχείο εφαρμογής από το *source*. Η πηγή μπορεί να
   είναι οποιοδήποτε από τα παρακάτω:

   * Το όνομα ενός φακέλου, ή ένα *path-like object* που αναφέρεται σε
     έναν φάκελο, οπότε θα δημιουργηθεί ένα νέο αρχείο εφαρμογής από
     το περιεχόμενο αυτού του φακέλου.

   * Το όνομα ενός υπάρχοντος αρχείου εφαρμογής, ή ένα *path-like
     object* που αναφέρεται σε ένα τέτοιο αρχείο, οπότε το αρχείο
     αντιγράφεται στο προορισμό (τροποποιώντας το για να
     αντικατοπτρίζει την τιμή που δίνεται για το όρισμα
     *interpreter*). Το όνομα του αρχείου θα πρέπει να περιλαμβάνει
     την επέκταση ".pyz", αν απαιτείται.

   * Ένα αντικείμενο αρχείου ανοιχτό για ανάγνωση σε λειτουργία bytes.
     Το περιεχόμενο του αρχείου θα πρέπει να είναι ένα αρχείο
     εφαρμογής, και το αντικείμενο αρχείου θεωρείται ότι είναι
     τοποθετημένο στην αρχή του αρχείου.

   Το όρισμα *target* καθορίζει που θα γραφτεί το αποτέλεσμα του
   αρχείου:

   * Αν είναι το όνομα ενός αρχείου, ή ένα *path-like object*, το
     αρχείο θα γραφτεί σε αυτό το αρχείο.

   * Αν είναι ένα ανοιχτό αντικείμενο αρχείου, το αρχείο θα γραφτεί σε
     αυτό το αντικείμενο αρχείου, το οποίο πρέπει να είναι ανοιχτό για
     εγγραφή σε λειτουργία bytes.

   * Αν το όρισμα προορισμού παραλειφθεί (ή είναι "None"), η πηγή
     πρέπει να είναι ένας φάκελος και ο προορισμός θα είναι ένα αρχείο
     με το ίδιο όνομα με την πηγή, με μια επέκταση ".pyz"
     προστιθέμενη.

   Το όρισμα *interpreter* καθορίζει το όνομα του διερμηνέα Python με
   τον οποίο θα εκτελείται το αρχείο. Γράφεται ως μια γραμμή "shebang"
   στην αρχή του αρχείου. Σε POSIX, αυτό θα ερμηνευτεί από το
   λειτουργικό σύστημα, και σε Windows θα διαχειριστεί από τον
   διερμηνέα Python. Η παράλειψη του *interpreter* έχει ως αποτέλεσμα
   να μην γραφτεί καμία γραμμή shebang. Αν καθοριστεί ένας διερμηνέας,
   και ο προορισμός είναι ένα όνομα αρχείου, θα τεθεί το εκτελέσιμο
   bit του αρχείου προορισμού.

   Το όρισμα *main* καθορίζει το όνομα μιας καλούμενης συνάρτησης που
   θα χρησιμοποιηθεί ως το κύριο πρόγραμμα για το αρχείο. Μπορεί να
   καθοριστεί μόνο αν η πηγή είναι ένας φάκελος, και η πηγή δεν
   περιέχει ήδη ένα αρχείο "__main__.py". Το όρισμα *main* θα πρέπει
   να έχει τη μορφή "pkg.module:callable" και το αρχείο θα εκτελείται
   με την εισαγωγή "pkg.module" και την εκτέλεση της δεδομένης
   καλούμενης συνάρτησης χωρίς ορίσματα. Είναι σφάλμα να παραλειφθεί
   το *main* αν η πηγή είναι ένας φάκελος και δεν περιέχει ένα αρχείο
   "__main__.py", καθώς διαφορετικά το παραγόμενο αρχείο δεν θα ήταν
   εκτελέσιμο.

   Το προαιρετικό όρισμα *filter* καθορίζει μια συνάρτηση callback που
   περνάει ένα αντικείμενο Path που αναπαριστά το μονοπάτι του αρχείου
   που προστίθεται (σχετικό με τον φάκελο πηγής). Θα πρέπει να
   επιστρέφει "True" αν το αρχείο πρέπει να προστεθεί.

   Το προαιρετικό όρισμα *compressed* καθορίζει αν τα αρχεία
   συμπιέζονται. Αν οριστεί σε "True", τα αρχεία στο αρχείο
   συμπιέζονται με τη μέθοδο deflate. Διαφορετικά, τα αρχεία
   αποθηκεύονται χωρίς συμπίεση. Αυτό το όρισμα δεν έχει καμία
   επίδραση κατά την αντιγραφή ενός υπάρχοντος αρχείου.

   Αν ένα αντικείμενο αρχείου καθοριστεί για το *source* ή το
   *target*, είναι ευθύνη του καλούντος να το κλείσει μετά την κλήση
   της create_archive.

   Κατά την αντιγραφή ενός υπάρχοντος αρχείου, τα αντικείμενα αρχείων
   που παρέχονται χρειάζονται μόνο τις μεθόδους "read" και "readline",
   ή "write". Όταν δημιουργείται ένα αρχείο από έναν φάκελο, αν το
   target είναι ένα αντικείμενο αρχείου, θα περαστεί στην κλάση
   "zipfile.ZipFile" και πρέπει να παρέχει τις μεθόδους που χρειάζεται
   αυτή η κλάση.

   Άλλαξε στην έκδοση 3.7: Προστέθηκαν οι παράμετροι *filter* και
   *compressed*.

zipapp.get_interpreter(archive)

   Επιστρέφει τον διερμηνέα που καθορίζεται στη γραμμή "#!" στην αρχή
   του αρχείου. Αν δεν υπάρχει γραμμή "#!", επιστρέφει "None". Το
   *archive* μπορεί να είναι ένα όνομα αρχείου ή ένα αντικείμενο που
   μοιάζει με αρχείο και είναι ανοιχτό για ανάγνωση σε bytes.


Παραδείγματα
============

Συσκευάζει έναν φάκελο σε ένα αρχείο, και το εκτελεί.

   $ python -m zipapp myapp
   $ python myapp.pyz
   <output from myapp>

Το ίδιο μπορεί να γίνει χρησιμοποιώντας τη συνάρτηση
"create_archive()":

   >>> import zipapp
   >>> zipapp.create_archive('myapp', 'myapp.pyz')

Για να κάνετε την εφαρμογή άμεσα εκτελέσιμη σε POSIX, καθορίστε έναν
διερμηνέα που θα χρησιμοποιηθεί.

   $ python -m zipapp myapp -p "/usr/bin/env python"
   $ ./myapp.pyz
   <output from myapp>

Για να αντικαταστήσετε τη γραμμή shebang σε ένα υπάρχον αρχείο,
δημιουργήστε ένα τροποποιημένο αρχείο χρησιμοποιώντας τη συνάρτηση
"create_archive()":

   >>> import zipapp
   >>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')

Για να ενημερώσετε το αρχείο στη θέση του, κάντε την αντικατάσταση στη
μνήμη χρησιμοποιώντας ένα αντικείμενο "BytesIO", και στη συνέχεια
αντικαταστήστε την πηγή. Σημειώστε ότι υπάρχει κίνδυνος κατά την
αντικατάσταση ενός αρχείου στη θέση του ότι ένα σφάλμα θα οδηγήσει
στην απώλεια του αρχικού αρχείου. Αυτός ο κώδικας δεν προστατεύει από
τέτοια σφάλματα, αλλά ο κώδικας παραγωγής θα πρέπει να το κάνει.
Επίσης, αυτή η μέθοδος θα λειτουργήσει μόνο αν το αρχείο χωράει στη
μνήμη:

   >>> import zipapp
   >>> import io
   >>> temp = io.BytesIO()
   >>> zipapp.create_archive('myapp.pyz', temp, '/usr/bin/python2')
   >>> with open('myapp.pyz', 'wb') as f:
   >>>     f.write(temp.getvalue())


Καθορισμός του Διερμηνέα
========================

Σημειώστε ότι αν καθορίσετε έναν διερμηνέα και στη συνέχεια διανείμετε
το αρχείο εφαρμογής σας, πρέπει να διασφαλίσετε ότι ο διερμηνέας που
χρησιμοποιείται είναι φορητός. Ο διερμηνέας Python για Windows
υποστηρίζει τις περισσότερες κοινές μορφές γραμμής "#!" POSIX, αλλά
υπάρχουν και άλλα ζητήματα που πρέπει να ληφθούν υπόψη:

* Αν χρησιμοποιήσετε "/usr/bin/env python" (ή άλλες μορφές της εντολής
  "python", όπως "/usr/bin/python"), πρέπει να λάβετε υπόψη ότι οι
  χρήστες σας μπορεί να έχουν είτε Python 2 είτε Python 3 ως
  προεπιλογή, και να γράψετε τον κώδικά σας ώστε να λειτουργεί και
  στις δύο εκδόσεις.

* Αν χρησιμοποιήσετε μια ρητή έκδοση, για παράδειγμα "/usr/bin/env
  python3", η εφαρμογή σας δεν θα λειτουργήσει για χρήστες που δεν
  έχουν αυτή την έκδοση. (Αυτό μπορεί να είναι αυτό που θέλετε αν δεν
  έχετε κάνει τον κώδικά σας συμβατό με την Python 2).

* Δεν υπάρχει τρόπος να πείτε "python X.Y ή νεότερη", οπότε να είστε
  προσεκτικοί όταν χρησιμοποιείτε μια ακριβή έκδοση όπως "/usr/bin/env
  python3.4", καθώς θα χρειαστεί να αλλάξετε τη γραμμή shebang για
  χρήστες της Python 3.5, για παράδειγμα.

Συνήθως, θα πρέπει να χρησιμοποιήσετε ένα "/usr/bin/env python2" ή
"/usr/bin/env python3", ανάλογα με το αν ο κώδικάς σας είναι γραμμένος
για την Python 2 ή 3.


Δημιουργία Αυτόνομων Εφαρμογών με το zipapp
===========================================

Χρησιμοποιώντας το module "zipapp", είναι δυνατό να δημιουργηθούν
αυτόνομες εφαρμογές Python, οι οποίες μπορούν να διανεμηθούν σε
τελικούς χρήστες που χρειάζονται μόνο να έχουν εγκατεστημένη μια
κατάλληλη έκδοση της Python στο σύστημά τους. Το κλειδί για να γίνει
αυτό είναι να συμπεριληφθούν όλες οι εξαρτήσεις της εφαρμογής στο
αρχείο, μαζί με τον κώδικα της εφαρμογής.

Τα βήματα για τη δημιουργία ενός αυτόνομου αρχείου είναι τα εξής:

1. Δημιουργήστε την εφαρμογή σας σε έναν φάκελο όπως συνήθως, έτσι
   ώστε να έχετε έναν φάκελο "myapp" που περιέχει ένα αρχείο
   "__main__.py" και οποιονδήποτε υποστηρικτικό κώδικα εφαρμογής.

2. Εγκαταστήστε όλες τις εξαρτήσεις της εφαρμογής σας στον φάκελο
   "myapp", χρησιμοποιώντας το pip:

      $ python -m pip install -r requirements.txt --target myapp

   (αυτό υποθέτει ότι έχετε τις απαιτήσεις του έργου σας σε ένα αρχείο
   "requirements.txt" - αν όχι, μπορείτε απλώς να καταγράψετε τις
   εξαρτήσεις χειροκίνητα στη γραμμή εντολών του pip).

3. Συσκευάστε την εφαρμογή χρησιμοποιώντας:

      $ python -m zipapp -p "interpreter" myapp

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

Σε Unix, το αρχείο "myapp.pyz" είναι εκτελέσιμο όπως είναι. Μπορείτε
να μετονομάσετε το αρχείο για να αφαιρέσετε την επέκταση ".pyz" αν
προτιμάτε ένα "καθαρό" όνομα εντολής. Σε Windows, το αρχείο
"myapp.pyz[w]" είναι εκτελέσιμο λόγω του γεγονότος ότι ο διερμηνέας
Python καταχωρεί τις επεκτάσεις αρχείων ".pyz" και ".pyzw" κατά την
εγκατάσταση.


Προειδοποιήσεις
---------------

Αν η εφαρμογή σας εξαρτάται από ένα πακέτο που περιλαμβάνει μια
επέκταση C, αυτό το πακέτο δεν μπορεί να εκτελεστεί από ένα αρχείο zip
(αυτό είναι περιορισμός του λειτουργικού συστήματος, καθώς ο
εκτελέσιμος κώδικας πρέπει να είναι παρών στο σύστημα αρχείων για να
τον φορτώσει ο φορτωτής του λειτουργικού συστήματος). Σε αυτή την
περίπτωση, μπορείτε να εξαιρέσετε αυτή την εξάρτηση από το αρχείο zip,
και είτε να απαιτήσετε από τους χρήστες σας να το έχουν εγκατεστημένο,
είτε να το αποστείλετε μαζί με το αρχείο zip και να προσθέσετε κώδικα
στο "__main__.py" για να συμπεριλάβετε τον φάκελο που περιέχει το
αποσυμπιεσμένο module στο "sys.path". Σε αυτή την περίπτωση, θα πρέπει
να διασφαλίσετε ότι θα αποστείλετε κατάλληλα δυαδικά αρχεία για την
αρχιτεκτονική/αρχιτεκτονικές (και ενδεχομένως να επιλέξετε την
κατάλληλη έκδοση για να προσθέσετε στο "sys.path" κατά τη διάρκεια
εκτέλεσης, με βάση τη μηχανή του χρήστη).


Η Μορφή Αρχείου Εφαρμογής Zip της Python
========================================

Η Python μπορεί να εκτελεί αρχεία zip που περιέχουν ένα αρχείο
"__main__.py" από την έκδοση 2.6. Για να εκτελεστεί από την Python,
ένα αρχείο εφαρμογής απλά πρέπει να είναι ένα τυπικό αρχείο zip που
περιέχει ένα αρχείο "__main__.py" το οποίο θα εκτελείται ως το σημείο
εισόδου για την εφαρμογή. Όπως συνήθως για οποιοδήποτε Python script,
ο γονέας του script (σε αυτή την περίπτωση το αρχείο zip) θα
τοποθετηθεί στο "sys.path" και έτσι περαιτέρω modules μπορούν να
εισαχθούν από το αρχείο zip.

Η μορφή αρχείου zip επιτρέπει την προσθήκη αυθαίρετων δεδομένων στην
αρχή ενός αρχείου zip. Η μορφή αρχείου εφαρμογής zip χρησιμοποιεί αυτή
την ικανότητα για να προσθέσει μια τυπική γραμμή "shebang" POSIX στην
αρχή του αρχείου ("#!/path/to/interpreter").

Επίσημα, η μορφή αρχείου εφαρμογής zip της Python είναι επομένως:

1. Μια προαιρετική γραμμή shebang, που περιέχει τους χαρακτήρες
   "b'#!'" ακολουθούμενους από ένα όνομα διερμηνέα, και στη συνέχεια
   έναν χαρακτήρα newline ("b'\n'"). Το όνομα του διερμηνέα μπορεί να
   είναι οτιδήποτε αποδεκτό από την επεξεργασία "shebang" του
   λειτουργικού συστήματος, ή τον διερμηνέα Python σε Windows. Ο
   διερμηνέας θα πρέπει να κωδικοποιείται σε UTF-8 σε Windows, και σε
   "sys.getfilesystemencoding()" σε POSIX.

2. Τυπικά δεδομένα αρχείου zip, όπως παράγονται από το module
   "zipfile". Το περιεχόμενο του αρχείου zip *πρέπει* να περιλαμβάνει
   ένα αρχείο "__main__.py" (το οποίο πρέπει να βρίσκεται στο "root"
   του αρχείου zip - δηλαδή, δεν μπορεί να βρίσκεται σε υποφάκελο). Τα
   δεδομένα του αρχείου zip μπορεί να είναι συμπιεσμένα ή μη
   συμπιεσμένα.

Αν ένα αρχείο εφαρμογής έχει μια γραμμή shebang, μπορεί να έχει
ρυθμιστεί το εκτελέσιμο bit σε συστήματα POSIX, για να επιτρέπεται η
άμεση εκτέλεσή του.

Δεν υπάρχει απαίτηση να χρησιμοποιούνται τα εργαλεία σε αυτό το module
για τη δημιουργία αρχείων εφαρμογής - το module είναι μια ευκολία,
αλλά τα αρχεία σε παραπάνω μορφή που δημιουργούνται με οποιονδήποτε
τρόπο είναι αποδεκτά από την Python.
