******************
**** PlWN API ****
******************

PlWN API umożliwia:
   - wyszukiwanie synsetów i jednostek leksykalnych w Słowosieci;
   - dostęp do własności synsetów i jednostek leksykalnych, oraz ich relacji;
   - eksport całości bądź części Słowosieci do grafu.

To README jest krótką, tymczasową instrukcją do wersji beta PlWN API.
Interfejs oraz funkcjonalność mogą ulec zmianie.

=============
Inicjalizacja
=============

   >>> import plwn
   >>> wn = plwn.load('plwn-3.0.db', 'sqlite3')

=================
Zrzuty baz danych
=================

Na ten moment, zalecany jest dostęp do bazy danych Słowosieci poprzez zrzuty do
plików SQLite, "plwn-X.db" (gdzie X to wersja Słowosieci). Zrzuty powinny
były zostać udostępnione razem z API.

==============
Funkcjonalność
==============

Opis funkcjonalności jest dostępny poprzez docstringi modułu plwn/bases.py

   $ pydoc plwn.bases

Dodatkowo, w plwn/_pos.py znajduje się lista stałych wartości part-of-speech
używanych przez API.

Zgodnie z konwencją przyjętą przez Python 3, większość metod zwracających
kolekcje obiektów zwraca je w postaci generatorów.

   >>> wn.lexical_units(lemma=u'pies')
   TupWrapper(<generator object <genexpr> at 0x7f1048583410>)

Jeśli celem zapytania jest iteracja po wynikach, nie potrzeba niczego więcej.

   >>> for lu in wn.lexical_units(lemma=u'pies'):
   >>>   print(lu.id)
   5563
   52245
   ...

Aby otrzymać listę (albo inną kolekcję), należy rzutować otrzymany obiekt.

   >>> list(wn.lexical_units(lemma=u'pies'))
   [<LexicalUnit id=5563 lemma=u'pies' pos=u'noun' variant=1>,
    <LexicalUnit id=52245 lemma=u'pies' pos=u'noun' variant=2>,
    ...
   ]

Dla wygody w trybie interaktywnym Pythona, generatory są opakowane w obiekty
"TupWrapper", które umożliwiają rzutowanie generatora do typu krotki
poprzez "wywołanie" obiektu.

   >>> wn.lexical_units(lemma=u'pies')()
   (<LexicalUnit id=5563 lemma=u'pies' pos=u'noun' variant=1>,
    <LexicalUnit id=52245 lemma=u'pies' pos=u'noun' variant=2>,
    ...
   )

Jednak w przypadku pisania programów odwołujących się do API zalecane jest
jawne rzutowanie zwracanych generatorów. "Explicit is better than implicit."