"cgi" --- wsparcie dla wspólnego sprzęgu bramki - z ang. - Common Gateway Interface
***********************************************************************************

**Source code:** Lib/cgi.py

Zdezaprobowane w wersji 3.11, zostanie usunięte w wersji 3.13: The
"cgi" module is deprecated (see **PEP 594** for details and
alternatives).The "FieldStorage" class can typically be replaced with
"urllib.parse.parse_qsl()" for "GET" and "HEAD" requests, and the
"email.message" module or multipart for "POST" and "PUT". Most utility
functions have replacements.

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

Wspierający moduł dla skryptów sprzęgu wspólnej bramki (z ang. CGI).

Ten moduł definiuje pewną liczbę użyteczności dla użycia przez skrypty
CGI napisane w języku pytonowskim.

The global variable "maxlen" can be set to an integer indicating the
maximum size of a POST request. POST requests larger than this size
will result in a "ValueError" being raised during parsing. The default
value of this variable is "0", meaning the request size is unlimited.

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms
"wasm32-emscripten" and "wasm32-wasi". See WebAssembly platforms for
more information.


Wprowadzenie
============

Skrypt CGI jest wywoływany przez serwer HTTP, zwykle aby przetworzyć
wejście użytkownika dostarczone przez HTML "<FORM>" lub element
"<ISINDEX>".

Najczęściej, Skrypty CGI przebywają w katalogu specjalnym serwera
"cgi-bin". Serwer HTTP umieszcza wszelkiego rodzaju informacje o
zapytaniu (takie jak nazwa hosta klienta, oczekiwany adres URL, ciąg
zapytania, i wiele innych dobrych rzeczy) w środowisku powłoki
skryptu, wykonuje skrypt i wysyła wyjście skryptu z powrotem do
klienta.

Wejście skryptu jest połączone z klientem także, i czasami dane
formularza są wczytywane tą drogą także; innym razem dane formularza
są przekazywane przez "ciąg zapytania" jako część adresu URL. Ten
moduł jest przeznaczony do zajmowania się różnymi przypadkami i
dostarczenia prostszego sprzęgu dla skryptu języka pytonowskiego. To
także dostarcza pewną liczbę użyteczności które pomagają w
odpluskwianiu skryptów zaś najnowszym dodatkiem jest wsparcie dla
załadowywania plików przez formularz (jeśli twoja przeglądarka to
wspomaga).

Wyjście skryptu CGI powinno składać się z dwóch sekcji, oddzielonych
pustą linią. Pierwszy rozdział zawiera liczbę nagłówków, mówiąc
klientowi jakiego rodzaju dane nastąpią potem. Kod języka
pytonowskiego aby wytworzyć minimalny rozdział nagłówkowy wygląda
następująco:

   print("Content-Type: text/html")    # HTML is following
   print()                             # blank line, end of headers

Drugi rozdziałem jest zwykle HTML, który pozwala oprogramowaniu
klienta wyświetlić ładnie sformatowany tekst z nagłówkiem, obrazkami w
-jednej-linii itp. Tu jest kod języka pytonowskiego który drukuje
prosty kawałek HTML-a:

   print("<TITLE>CGI script output</TITLE>")
   print("<H1>This is my first CGI script</H1>")
   print("Hello, world!")


Użycie modułu cgi
=================

Zacznij przez napisanie "import cgi".

Gdy piszesz nowy skrypt, rozważ dodanie tych linii:

   import cgitb
   cgitb.enable()

This activates a special exception handler that will display detailed
reports in the web browser if any errors occur.  If you'd rather not
show the guts of your program to users of your script, you can have
the reports saved to files instead, with code like this:

   import cgitb
   cgitb.enable(display=0, logdir="/path/to/logdir")

Jest bardzo przydatnym użycie tej właściwości w czasie rozwijania
skryptu. Raporty produkowane przez "cgitb" dostarczają informację
która może oszczędzić Ci wiele czasu w śledzeniu błędów. Możesz zawsze
usunąć "cgitb" linię później gdy przetestowałeś swój skrypt i jesteś
pewien że działa on prawidłowo.

To get at submitted form data, use the "FieldStorage" class. If the
form contains non-ASCII characters, use the *encoding* keyword
parameter set to the value of the encoding defined for the document.
It is usually contained in the META tag in the HEAD section of the
HTML document or by the *Content-Type* header.  This reads the form
contents from the standard input or the environment (depending on the
value of various environment variables set according to the CGI
standard).  Since it may consume standard input, it should be
instantiated only once.

The "FieldStorage" instance can be indexed like a Python dictionary.
It allows membership testing with the "in" operator, and also supports
the standard dictionary method "keys()" and the built-in function
"len()".  Form fields containing empty strings are ignored and do not
appear in the dictionary; to keep such values, provide a true value
for the optional *keep_blank_values* keyword parameter when creating
the "FieldStorage" instance.

Dla przykładu, następujący kod (który zakłada, że nagłówek *Content-
Type* i puste linie zostały już wydrukowane) sprawdza czy pola "nazwa"
i "addr" zostały oba ustawione na nie-pusty ciąg znaków:

   form = cgi.FieldStorage()
   if "name" not in form or "addr" not in form:
       print("<H1>Error</H1>")
       print("Please fill in the name and addr fields.")
       return
   print("<p>name:", form["name"].value)
   print("<p>addr:", form["addr"].value)
   ...further form processing here...

Here the fields, accessed through "form[key]", are themselves
instances of "FieldStorage" (or "MiniFieldStorage", depending on the
form encoding). The "value" attribute of the instance yields the
string value of the field.  The "getvalue()" method returns this
string value directly; it also accepts an optional second argument as
a default to return if the requested key is not present.

If the submitted form data contains more than one field with the same
name, the object retrieved by "form[key]" is not a "FieldStorage" or
"MiniFieldStorage" instance but a list of such instances.  Similarly,
in this situation, "form.getvalue(key)" would return a list of
strings. If you expect this possibility (when your HTML form contains
multiple fields with the same name), use the "getlist()" method, which
always returns a list of values (so that you do not need to special-
case the single item case).  For example, this code concatenates any
number of username fields, separated by commas:

   value = form.getlist("username")
   usernames = ",".join(value)

If a field represents an uploaded file, accessing the value via the
"value" attribute or the "getvalue()" method reads the entire file in
memory as bytes.  This may not be what you want.  You can test for an
uploaded file by testing either the "filename" attribute or the "file"
attribute.  You can then read the data from the "file" attribute
before it is automatically closed as part of the garbage collection of
the "FieldStorage" instance (the "read()" and "readline()" methods
will return bytes):

   fileitem = form["userfile"]
   if fileitem.file:
       # It's an uploaded file; count lines
       linecount = 0
       while True:
           line = fileitem.file.readline()
           if not line: break
           linecount = linecount + 1

"FieldStorage" objects also support being used in a "with" statement,
which will automatically close them when done.

If an error is encountered when obtaining the contents of an uploaded
file (for example, when the user interrupts the form submission by
clicking on a Back or Cancel button) the "done" attribute of the
object for the field will be set to the value -1.

Standard ładowania pliku przewiduje możliwość załadowania wielu plików
z jednego pola (używając rekursywnego kodowania *multipart/**). Gdy to
się zdarzy, element będzie słowniko-podobnym elementem "FieldStorage".
To może być określone przez sprawdzenie właściwości "type", która
powinna być *multipart/form-data* (lub byćmoże inny typ MIME pasujący
do *multipart/**). W tym przypadku może być on iterowany rekursywnie
tak, jak przedmiot formularza nadrzędnego poziomu.

Gdy formularz jest podawany w "starym" formacie (jako ciąg zapytania
lub pojedyncza część danych typu *application/x-www-form-urlencoded*),
wszystkie elementy właściwie będą przykładami uogólnienia
"MiniFieldStorage". W tym przypadku, właściwości "list", "file", i
"filename" są zawsze "None".

Formularz podany przez sposób postępowania POST który także zawiera
ciąg zapytania będzie zawierał zarówno elementy "FieldStorage" jak i
"MiniFieldStorage".

Zmienione w wersji 3.4: The "file" attribute is automatically closed
upon the garbage collection of the creating "FieldStorage" instance.

Zmienione w wersji 3.5: Added support for the context management
protocol to the "FieldStorage" class.


Sprzęg Wyższego Poziomu (Higher Level Interface)
================================================

Poprzednia sekcja wyjaśnia jak czytać dane z formularza CGI używając
uogólnienia "FieldStorage". Ten rozdział opisuje sprzęg wyższego
rzędu, który został dodany do tego uogólnienia aby pozwolić robić to w
bardziej czytelny i intuicyjny sposób. Sprzęg nie powoduje że techniki
opisane w poprzednich rozdziałach stają się zbędne --- one są wciąż
użyteczne aby wykonywać ładowanie plików efektywnie, dla przykładu.

Sprzęg składa się z dwóch prostych sposobów postępowania. Używając
sposobów postępowania możesz przetwarzać dane w zastępczy sposób bez
konieczności martwienia się czy tylko jedna czy więcej danych zostało
opublikowanych pod daną nazwą.

W poprzednim rozdziale, dowiedziałeś się jak pisać następujący kod za
każdym razem gdy spodziewałeś się że użytkownik opublikuje więcej niż
jedną wartość pod jedną nazwą:

   item = form.getvalue("item")
   if isinstance(item, list):
       # The user is requesting more than one item.
   else:
       # The user is requesting only one item.

Ta sytuacja jest obecna dla przykładu gdy formularz zawiera grupę
wielu pól zaznaczania o tej samej nazwie:

   <input type="checkbox" name="item" value="1" />
   <input type="checkbox" name="item" value="2" />

W większości przypadków, jednakże, istnieje tylko jedna urządzenie
formularza o określonej nazwie w formularzu i wtedy oczekujesz i
potrzebujesz tylko jednej wartości powiązanej z tą nazwą. Więc piszesz
skrypt zawierający dla przykładu ten kod:

   user = form.getvalue("user").upper()

Problem z kodem polega na tym, że nigdy nie powinieneś oczekiwać, że
klient dostarczy właściwe wpisy do twoich skryptów. Dla przykładu,
jeśli ciekawy użytkownik dołoży jeszcze jedną parę "user=foo" do ciągu
zapytania, wtedy skrypt ulegnie wypadkowi, ponieważ w tej sytuacji
wywołanie sposobu postępowania "getvalue("user")" zwróci listę zamiast
ciągu znaków. Wywołanie sposobu postępowania "upper()" na liście nie
jest prawidłowe (gdyż listy nie mają sposobów postępowania o tej
nazwie) i kończy się wyjątkiem "AttributeError".

Zatem, właściwym sposobem aby wczytywać dane formularza było zawsze
używanie kodu który sprawdza czy otrzymana wartość jest pojedynczą
wartością czy listą wartości. To jest irytujące i prowadzi do mniej
czytelnych skryptów.

A more convenient approach is to use the methods "getfirst()" and
"getlist()" provided by this higher level interface.

FieldStorage.getfirst(name, default=None)

   Ten sposób postępowania zawsze zwraca tylko jedną wartość związaną
   z polem formularza *name*. Sposób postępowania zwraca tylko
   pierwszą wartość w przypadku gdy więcej wartości zostało
   opublikowanych pod taką nazwą. Proszę zauważ że kolejność w jakiej
   wartości są otrzymywane może różnić się między przeglądarkami i nie
   powinien liczyć się. [1] Jeśli żadne takie pole formularza ani
   wartość nie istnieje wtedy sposób postępowania zwraca wartość
   określoną przez opcjonalny parametr *domyślny* - z ang - *default*.
   Ten parametr domyślnie równy jest "None" jeśli nie jest określony.

FieldStorage.getlist(name)

   Ten sposób postępowania zawsze zwraca listę wartości związaną z
   polem formularza *name*. Ten sposób postępowania zwraca pustą listę
   jeśli żadne pole ani wartość nie istnieje dla *nazwy* - z ang. -
   *name*. Zwraca listę składającą się z jednego elementu jeśli tylko
   jedna taka wartość istnieje.

Używając tych sposobów postępowania możesz napisać ładny zgrabny kod:

   import cgi
   form = cgi.FieldStorage()
   user = form.getfirst("user", "").upper()    # This way it's safe.
   for item in form.getlist("item"):
       do_something(item)


Zadania
=======

Te są użyteczne jeśli chcesz więcej kontrolować, lub jeśli chcesz
zatrudnić niektóre z algorytmów wypełnionych w tym module w innych
przypadkach.

cgi.parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator='&')

   Parse a query in the environment or from a file (the file defaults
   to "sys.stdin").  The *keep_blank_values*, *strict_parsing* and
   *separator* parameters are passed to "urllib.parse.parse_qs()"
   unchanged.

   Zdezaprobowane w wersji 3.11, zostanie usunięte w wersji 3.13: This
   function, like the rest of the "cgi" module, is deprecated. It can
   be replaced by calling "urllib.parse.parse_qs()" directly on the
   desired query string (except for "multipart/form-data" input, which
   can be handled as described for "parse_multipart()").

cgi.parse_multipart(fp, pdict, encoding='utf-8', errors='replace', separator='&')

   Parse input of type *multipart/form-data* (for  file uploads).
   Arguments are *fp* for the input file, *pdict* for a dictionary
   containing other parameters in the *Content-Type* header, and
   *encoding*, the request encoding.

   Returns a dictionary just like "urllib.parse.parse_qs()": keys are
   the field names, each value is a list of values for that field. For
   non-file fields, the value is a list of strings.

   This is easy to use but not much good if you are expecting
   megabytes to be uploaded --- in that case, use the "FieldStorage"
   class instead which is much more flexible.

   Zmienione w wersji 3.7: Added the *encoding* and *errors*
   parameters.  For non-file fields, the value is now a list of
   strings, not bytes.

   Zmienione w wersji 3.10: Added the *separator* parameter.

   Zdezaprobowane w wersji 3.11, zostanie usunięte w wersji 3.13: This
   function, like the rest of the "cgi" module, is deprecated. It can
   be replaced with the functionality in the "email" package (e.g.
   "email.message.EmailMessage"/"email.message.Message") which
   implements the same MIME RFCs, or with the multipart PyPI project.

cgi.parse_header(string)

   Wczytaj nagłówek MIME (taki, jak *Content-Type*) do głównej
   wartości i słownika parametrów.

   Zdezaprobowane w wersji 3.11, zostanie usunięte w wersji 3.13: This
   function, like the rest of the "cgi" module, is deprecated. It can
   be replaced with the functionality in the "email" package, which
   implements the same MIME RFCs.For example, with
   "email.message.EmailMessage":

      from email.message import EmailMessage
      msg = EmailMessage()
      msg['content-type'] = 'application/json; charset="utf8"'
      main, params = msg.get_content_type(), msg['content-type'].params

cgi.test()

   Robust test CGI script, usable as main program. Writes minimal HTTP
   headers and formats all information provided to the script in HTML
   format.

cgi.print_environ()

   Formatuje środowisko powłoki w HTML-u

cgi.print_form(form)

   Formatuje formularz w HTML-u.

cgi.print_directory()

   Formatuje obecny katalog w HTML-u.

cgi.print_environ_usage()

   Drukuje listę użytecznych (używanych przez CGI) zmiennych
   środowiskowych w HTML-u.


Troska o bezpieczeństwo
=======================

There's one important rule: if you invoke an external program (via
"os.system()", "os.popen()" or other functions with similar
functionality), make very sure you don't pass arbitrary strings
received from the client to the shell.  This is a well-known security
hole whereby clever hackers anywhere on the web can exploit a gullible
CGI script to invoke arbitrary shell commands.  Even parts of the URL
or field names cannot be trusted, since the request doesn't have to
come from your form!

Aby trzymać się bezpiecznej strony, jeśli przekazujesz ciąg znaków
otrzymany z formularza do polecenia powłoki, powinieneś upewnić się,
że ciąg znaków zawiera tylko znaki alfanumeryczne, ukośniki,
podkreślenia i kropki.


Instalowanie twojego skryptu CGI na systemie Unix-owym
======================================================

Przeczytaj dokumentację dla twojego serwera HTTP i sprawdź u swojego
administratora systemu aby dowiedzieć się który katalog powinien być
użyty dla instalowania skryptów CGI; zwykle to jest katalog "cgi-bin"
w drzewie serwera.

Upewnij się że twój skrypt jest czytelny i wykonywalny przez "innych";
tryb pliku Unix-a powinien być "0o755" ósemkowo (użyj "chmod 0755
nazwa-pliku"). Upewnij się, że pierwsza linia skryptu zawiera "#!"
zaczynając w kolumnie 1 po której następuje ścieżka dostępu do pliku
programu interpretującego polecenia języka pytonowskiego, dla
przykładu:

   #!/usr/local/bin/python

Upewnij się że program interpretujący polecenia języka pytonowskiego
istnieje i jest wykonywalny przez "innych".

Upewnij się, że jakiekolwiek pliki które twój skrypt chce odczytać lub
zapisać są czytelne i możliwe do zapisania odpowiednio, przez "innych"
--- ich tryb powinien być "0o644" dla czytelnych i "0o666" dla
możliwych do zapisania. To jest ponieważ z powodów bezpieczeństwa,
serwer HTTP wykonuje twój skrypt jako użytkownik "nikt" - z ang. -
"nobody" bez żadnych szczególnych przywilejów. Może tylko wczytywać
(zapisywać, wykonywać) pliki które wszyscy mogą czytać (zapisać,
wykonać). Bierzący katalog w czasie wykonania jest także inny (jest to
zwykle katalog serwera cgi-bin) i ustawienie zmiennych środowiskowych
jest także inne od tego które dostajesz gdy się zalogujesz. W
szczególności, nie licz na ścieżkę przeszukiwania pod kątem plików
wykonywalnych ("PATH") ani na ścieżkę przeszukiwania modułów języka
pytonowskiego ("PYTHONPATH"), że będą ustawione na cokolwiek
interesującego.

Jeśli potrzebujesz załadować moduły z katalogu który nie jest domyślną
ścieżką przeszukiwania modułów języka pytonowskiego, możesz zmienić
ścieżkę w twoim skrypcie, przez importowaniem innych modułów. Dla
przykładu:

   import sys
   sys.path.insert(0, "/usr/home/joe/lib/python")
   sys.path.insert(0, "/usr/local/lib/python")

(W ten sposób, katalog wstawiony jako ostatni będzie przeszukiwany
jako pierwszy!)

Instrukcje dla nie-Unixowych systemów będą różne; Sprawdź dokumentację
serwera HTTP (będzie zwykle miała sekcję o skryptach CGI).


Sprawdzanie twoich skryptów CGI
===============================

Niestety, skrypt CGI zwykle nie uruchomi się gdy spróbujesz go
uruchomić z wiersza poleceń i skrypt który działa dobrze z wiersza
polecenia może zawieźć nieoczekiwanie gdy uruchomiony z serwera. Jest
jeden powód dla którego wciąż powinieneś testować swój skrypt z
wiersza polecenia: jeśli zawiera błąd składniowy, program
interpretujący polecenia języka pytonowskiego nie wykona go w ogóle, a
serwer HTTP najprawdopodobniej wyśle tajemniczy komunikat o błędzie do
klienta.

Zakładając, że twój skrypt nie ma błędów składniowych, a jednak wciąż
nie działa, nie masz wyboru, tylko musisz czytać dalej.


Odpluskwianie skryptów CGI
==========================

First of all, check for trivial installation errors --- reading the
section above on installing your CGI script carefully can save you a
lot of time.  If you wonder whether you have understood the
installation procedure correctly, try installing a copy of this module
file ("cgi.py") as a CGI script.  When invoked as a script, the file
will dump its environment and the contents of the form in HTML format.
Give it the right mode etc., and send it a request.  If it's installed
in the standard "cgi-bin" directory, it should be possible to send it
a request by entering a URL into your browser of the form:

   http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

Jeśli zwróci błąd typu 404, wtedy serwer nie może znaleźć skryptu --
być może potrzebujesz zainstalować go w innych katalogu. Jeśli daje
inny błąd, istnieje problem instalacji który powinieneś naprawić zanim
spróbujesz iść dalej. Jeśli otrzymujesz ładnie sformatowany wypis
środowiska i zawartości formularza (w tym przypadku, pola powinny być
wypisane jako "addr" z wartością "At Home" i "name" z wartością "Joe
Blow"), plik skryptu "cgi.py" zostały zainstalowane poprawnie. Jeśli
wykonasz tę samą procedurę dla twojego własnego skryptu, powinieneś
móc go teraz odpluskwiać.

Następnym krokiem mogłoby być wezwanie zadania "test()" modułu "cgi" z
twojego skryptu: zamiana jej głównego kodu na pojedyncze stwierdzenie:

   cgi.test()

To powinno dać te same wyniki jak te otrzymane z zainstalowania samego
pliku "cgi.py".

Gdy zwykły skrypt języka pytonowskiego zgłasza nieobsłużony wyjątek
(dla jakiegokolwiek powodu: z powodu literówki w nazwie modułu, pliku
który nie może być otwarty, itp.), program interpretujący polecenia
języka pytonowskiego wypisuje ładny wypis i wychodzi. Podczas gdy
program interpretujący polecenia języka pytonowskiego będzie wciąż to
robił gdy twój skrypt CGI zgłosi wyjątek, najprawdopodobniej wypis
skończy w jednym z plików logów serwera HTTP, lub zostanie odrzucony
całkowicie.

Fortunately, once you have managed to get your script to execute
*some* code, you can easily send tracebacks to the web browser using
the "cgitb" module. If you haven't done so already, just add the
lines:

   import cgitb
   cgitb.enable()

na górę twojego skryptu. Wtedy spróbuj uruchomić go jeszcze raz; gdy
problem pojawi się znów, powinieneś zobaczyć szczegółowy raport, który
prawdopodobnie uczyni jasnym powód wypadku.

Jeśli podejrzewasz, że może być problem w importowaniu modułu "cgitb",
możesz użyć nawet jeszcze bardziej wydajnego podejścia (które używa
tylko modułów wbudowanych):

   import sys
   sys.stderr = sys.stdout
   print("Content-Type: text/plain")
   print()
   ...your code here...

To opiera się na programie interpretującym polecenia języka
pytonowskiego, że wydrukuje swój wypis. Typ treści wyjścia jest
ustawiony na zwykły tekst, co wyklucza całą obsługę HTML. Jeśli twój
skrypt działa, surowy HTML zostanie pokazany przez twojego klienta.
Jeśli zgłasza wyjątek, najprawdopodobniej po tym jak pierwsze linie
zostaną wypisane, wypis wsteczny zostanie wyświetlony. Ponieważ żadna
interpretacja HTML-a nie miejsca, wypis wsteczny będzie czytelny.


Typowe problemy i ich rozwiązania
=================================

* Większość serwerów HTTP przechowuje w przestrzeni wymiany wyjście ze
  skryptów CGI dopóki skrypt się nie zakończy. To oznacza, że nie jest
  możliwe wyświetlenie raportu postępu na wyświetlaczu klienta kiedy
  skrypt działa.

* Sprawdź instrukcje instalacyjne powyżej.

* Sprawdź pliki logu serwera HTTP. ("tail -f logfile" w oddzielnym
  oknie może być użyteczne!)

* Zawsze sprawdzaj skrypt dla błędów składniowych najpierw, przez
  wykonanie czegoś podobnego do "python script.py".

* Jeśli twój skrypt nie ma żadnych błędów składniowych, spróbuj dodać
  "import cgitb; cgitb.enable()" na górze skryptu.

* Gdy wywoływane są zewnętrzne programy upewnij się że mogą być
  znalezione. Zwykle to oznacza, że używanie nazw ścieżek absolutnych
  --- "PATH" nie jest zwykle ustawiana na użyteczną wartość skryptu
  CGI.

* Gdy wczytujesz lub zapisujesz zewnętrzne pliki, upewnij się że mogą
  one być wczytane lub zapisane przez userid pod którym twój skrypt
  CGI będzie działał: to jest typowo userid pod którym serwer sieci
  działa, lub pewny jawnie określony userid dla właściwości sieciowego
  serwera "suexec".

* Nie próbuj nadawać skryptowi CGI trybu set-uid. To nie działa na
  większości systemów, i jest odpowiedzialnością za bezpieczeństwo
  także.

-[ Przypisy ]-

[1] Zauważ że pewne niedawne wersje specyfikacji HTML-a określają w
    jakiej kolejności wartości pól powinny być dostarczone, ale
    wiedzieć czy zapytanie zostało otrzymane z odpowiadającej
    przeglądarki, czy też w ogóle z przeglądarki jest nużące i podatne
    na błędy.
