upd doc and setup
This commit is contained in:
FoxMaSk
@@ -1,2 +1,2 @@
|
||||
VERSION = (1, 3, 0) # PEP 386
|
||||
VERSION = (1, 4, 0) # PEP 386
|
||||
__version__ = ".".join([str(x) for x in VERSION])
|
||||
|
||||
@@ -3,12 +3,9 @@ import logging
|
||||
import aiohttp
|
||||
from aiohttp.http_exceptions import HttpProcessingError
|
||||
from aiohttp.client_exceptions import ClientResponseError
|
||||
# from aiohttp import HTTPError
|
||||
|
||||
|
||||
__author__ = 'foxmask'
|
||||
|
||||
|
||||
logging.basicConfig(format='%(message)s', level=logging.INFO)
|
||||
|
||||
__all__ = ['Wallabag']
|
||||
@@ -40,14 +37,14 @@ class Wallabag(object):
|
||||
"+https://github.com/foxmask/wallabag-api",
|
||||
aio_sess=None):
|
||||
"""
|
||||
init variable
|
||||
:param host: string url to the official API Wallabag
|
||||
:param token: string of the key provided by Wallabag
|
||||
:param client_id client id
|
||||
:param client_secret client secret
|
||||
:param extension: xml|json|txt|csv|pdf|epub|mobi|html
|
||||
:param user_agent
|
||||
:param aio_session aiohttp session
|
||||
init variable
|
||||
:param host: string url to the official API Wallabag
|
||||
:param token: string of the key provided by Wallabag
|
||||
:param client_id client id
|
||||
:param client_secret client secret
|
||||
:param extension: xml|json|txt|csv|pdf|epub|mobi|html
|
||||
:param user_agent
|
||||
:param aio_sess aiohttp session
|
||||
"""
|
||||
self.host = host
|
||||
self.client_id = client_id
|
||||
@@ -57,24 +54,18 @@ class Wallabag(object):
|
||||
self.user_agent = user_agent
|
||||
self.aio_sess = aio_sess
|
||||
if self.format not in self.EXTENTIONS:
|
||||
raise ValueError("format invalid {0} should be one of {1}".format(self.format, self.EXTENTIONS))
|
||||
|
||||
def get_host(self):
|
||||
"""
|
||||
get the host from which to get API
|
||||
:return host
|
||||
"""
|
||||
return self.host
|
||||
raise ValueError("format invalid {0} should be one of {1}".format(
|
||||
self.format, self.EXTENTIONS))
|
||||
|
||||
async def query(self, path, method='get', **params):
|
||||
"""
|
||||
Do a query to the System API
|
||||
Do a query to the System API
|
||||
|
||||
:param path: url to the API
|
||||
:param method: the kind of query to do
|
||||
:param params: a dict with all the
|
||||
necessary things to query the API
|
||||
:return json data
|
||||
:param path: url to the API
|
||||
:param method: the kind of query to do
|
||||
:param params: a dict with all the
|
||||
necessary things to query the API
|
||||
:return json data
|
||||
"""
|
||||
if method in ('get', 'post', 'patch', 'delete', 'put'):
|
||||
full_path = self.host + path
|
||||
@@ -94,17 +85,17 @@ class Wallabag(object):
|
||||
if resp.content_type.startswith('application/pdf') or \
|
||||
resp.content_type.startswith('application/epub'):
|
||||
return await resp.read()
|
||||
else:
|
||||
return await self.handle_json_response(resp)
|
||||
|
||||
return await self.handle_json_response(resp)
|
||||
else:
|
||||
raise ValueError('method expected: get, post, patch, delete, put')
|
||||
|
||||
@staticmethod
|
||||
async def handle_json_response(responses):
|
||||
"""
|
||||
get the json data response
|
||||
:param responses: the json response
|
||||
:return the json data without 'root' node
|
||||
get the json data response
|
||||
:param responses: the json response
|
||||
:return the json data without 'root' node
|
||||
"""
|
||||
if responses.status != 200:
|
||||
raise HttpProcessingError(code=responses.status,
|
||||
@@ -115,7 +106,7 @@ class Wallabag(object):
|
||||
except ClientResponseError as e:
|
||||
# sometimes json_data does not return any json() without
|
||||
# any error. This is due to the grabbing URL which "rejects"
|
||||
# the URL
|
||||
# the URL
|
||||
logging.error("Wallabag: aiohttp error {code} {message}"
|
||||
.format(code=e.code, message=e.message))
|
||||
return await json_data
|
||||
@@ -123,12 +114,12 @@ class Wallabag(object):
|
||||
@staticmethod
|
||||
def __get_attr(what, type_attr, value_attr, **kwargs):
|
||||
"""
|
||||
|
||||
:param what:
|
||||
:param type_attr:
|
||||
get the value of a parm
|
||||
:param what: string parm
|
||||
:param type_attr: type of parm
|
||||
:param value_attr:
|
||||
:param kwargs:
|
||||
:return:
|
||||
:return: value of the parm
|
||||
"""
|
||||
value = int(kwargs[what]) if type_attr == 'int' else kwargs[what]
|
||||
if what in kwargs and value in value_attr:
|
||||
@@ -137,23 +128,22 @@ class Wallabag(object):
|
||||
# ENTRIES
|
||||
async def get_entries(self, **kwargs):
|
||||
"""
|
||||
GET /api/entries.{_format}
|
||||
|
||||
GET /api/entries.{_format}
|
||||
Retrieve all entries. It could be filtered by many options.
|
||||
|
||||
Retrieve all entries. It could be filtered by many options.
|
||||
|
||||
:param kwargs: can contain one of the following filters
|
||||
archive: '0' or '1', default '0' filter by archived status.
|
||||
star: '0' or '1', default '0' filter by starred status.
|
||||
delete: '0' or '1', default '0' filter by deleted status.
|
||||
sort: 'created' or 'updated', default 'created'
|
||||
order: 'asc' or 'desc', default 'desc'
|
||||
page: int default 1 what page you want
|
||||
perPage: int default 30 result per page
|
||||
tags: list of tags url encoded.
|
||||
since: int default 0 from what timestamp you want
|
||||
Will returns entries that matches ALL tags
|
||||
:return data related to the ext
|
||||
:param kwargs: can contain one of the following filters
|
||||
archive: '0' or '1', default '0' filter by archived status.
|
||||
star: '0' or '1', default '0' filter by starred status.
|
||||
delete: '0' or '1', default '0' filter by deleted status.
|
||||
sort: 'created' or 'updated', default 'created'
|
||||
order: 'asc' or 'desc', default 'desc'
|
||||
page: int default 1 what page you want
|
||||
perPage: int default 30 result per page
|
||||
tags: list of tags url encoded.
|
||||
since: int default 0 from what timestamp you want
|
||||
Will returns entries that matches ALL tags
|
||||
:return data related to the ext
|
||||
"""
|
||||
# default values
|
||||
params = dict({'access_token': self.token,
|
||||
@@ -199,17 +189,16 @@ class Wallabag(object):
|
||||
|
||||
async def post_entries(self, url, title='', tags='', starred=0, archive=0):
|
||||
"""
|
||||
POST /api/entries.{_format}
|
||||
|
||||
POST /api/entries.{_format}
|
||||
Create an entry
|
||||
|
||||
Create an entry
|
||||
|
||||
:param url: the url of the note to store
|
||||
:param title: Optional, we'll get the title from the page.
|
||||
:param tags: tag1,tag2,tag3 a comma-separated list of tags.
|
||||
:param starred entry already starred
|
||||
:param archive entry already archived
|
||||
:return result
|
||||
:param url: the url of the note to store
|
||||
:param title: Optional, we'll get the title from the page.
|
||||
:param tags: tag1,tag2,tag3 a comma-separated list of tags.
|
||||
:param starred entry already starred
|
||||
:param archive entry already archived
|
||||
:return result
|
||||
"""
|
||||
params = {'access_token': self.token, 'url': url, 'title': title,
|
||||
'tags': tags, 'starred': starred, 'archive': archive}
|
||||
@@ -220,13 +209,12 @@ class Wallabag(object):
|
||||
|
||||
async def get_entry(self, entry):
|
||||
"""
|
||||
GET /api/entries/{entry}.{_format}
|
||||
|
||||
GET /api/entries/{entry}.{_format}
|
||||
Retrieve a single entry
|
||||
|
||||
Retrieve a single entry
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/entries/{entry}.{ext}'.format(entry=entry,
|
||||
@@ -235,20 +223,19 @@ class Wallabag(object):
|
||||
|
||||
async def patch_entries(self, entry, **kwargs):
|
||||
"""
|
||||
PATCH /api/entries/{entry}.{_format}
|
||||
|
||||
PATCH /api/entries/{entry}.{_format}
|
||||
Change several properties of an entry
|
||||
|
||||
Change several properties of an entry
|
||||
|
||||
:param entry: the entry to 'patch' / update
|
||||
:param kwargs: can contain one of the following
|
||||
title: string
|
||||
tags: a list of tags tag1,tag2,tag3
|
||||
archive: '0' or '1', default '0' archived the entry.
|
||||
star: '0' or '1', default '0' starred the entry
|
||||
delete: '0' or '1', default '0' flag as deleted.
|
||||
In case that you don't want to *really* remove it..
|
||||
:return data related to the ext
|
||||
:param entry: the entry to 'patch' / update
|
||||
:param kwargs: can contain one of the following
|
||||
title: string
|
||||
tags: a list of tags tag1,tag2,tag3
|
||||
archive: '0' or '1', default '0' archived the entry.
|
||||
star: '0' or '1', default '0' starred the entry
|
||||
delete: '0' or '1', default '0' flag as deleted.
|
||||
In case that you don't want to *really* remove it..
|
||||
:return data related to the ext
|
||||
"""
|
||||
# default values
|
||||
params = {'access_token': self.token,
|
||||
@@ -286,13 +273,12 @@ class Wallabag(object):
|
||||
|
||||
async def get_entry_export(self, entry):
|
||||
"""
|
||||
GET /api/entries/{entry}/export.{_format}
|
||||
|
||||
GET /api/entries/{entry}/export.{_format}
|
||||
Retrieve a single entry as a predefined format.
|
||||
|
||||
Retrieve a single entry as a predefined format.
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/entries/{entry}/export.{ext}'.format(entry=entry,
|
||||
@@ -301,14 +287,14 @@ class Wallabag(object):
|
||||
|
||||
async def patch_entry_reload(self, entry):
|
||||
"""
|
||||
PATCH /api/entries/{entry}/reload.{_format}
|
||||
|
||||
PATCH /api/entries/{entry}/reload.{_format}
|
||||
Reload an entry. An empty response with HTTP Status 304 will be send
|
||||
if we weren't able to update the content (because it hasn't changed
|
||||
or we got an error).
|
||||
|
||||
Reload an entry. An empty response with HTTP Status 304 will be send if we weren't able to update
|
||||
the content (because it hasn't changed or we got an error).
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/entries/{entry}/reload.{ext}'.format(entry=entry,
|
||||
@@ -317,13 +303,12 @@ class Wallabag(object):
|
||||
|
||||
async def delete_entries(self, entry):
|
||||
"""
|
||||
DELETE /api/entries/{entry}.{_format}
|
||||
|
||||
DELETE /api/entries/{entry}.{_format}
|
||||
Delete permanently an entry
|
||||
|
||||
Delete permanently an entry
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return result
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return result
|
||||
"""
|
||||
|
||||
params = {'Authorization': 'Bearer {}'.format(self.token)}
|
||||
@@ -333,16 +318,16 @@ class Wallabag(object):
|
||||
|
||||
async def entries_exists(self, url, urls=''):
|
||||
"""
|
||||
GET /api/entries/exists.{_format}
|
||||
|
||||
GET /api/entries/exists.{_format}
|
||||
Check if an entry exist by url.
|
||||
|
||||
Check if an entry exist by url.
|
||||
:param url string true An url Url to check if it exists
|
||||
:param urls string false An array of urls
|
||||
(?urls[]=http...&urls[]=http...) Urls (as an array)
|
||||
to check if it exists
|
||||
|
||||
:param url string true An url Url to check if it exists
|
||||
:param urls string false An array of urls (?urls[]=http...&urls[]=http...)
|
||||
Urls (as an array) to check if it exists
|
||||
|
||||
:return result
|
||||
:return result
|
||||
"""
|
||||
params = {'url': url,
|
||||
'urls': urls}
|
||||
@@ -354,13 +339,12 @@ class Wallabag(object):
|
||||
|
||||
async def get_entry_tags(self, entry):
|
||||
"""
|
||||
GET /api/entries/{entry}/tags.{_format}
|
||||
|
||||
GET /api/entries/{entry}/tags.{_format}
|
||||
Retrieve all tags for an entry
|
||||
|
||||
Retrieve all tags for an entry
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/entries/{entry}/tags.{ext}'.format(
|
||||
@@ -369,14 +353,13 @@ class Wallabag(object):
|
||||
|
||||
async def post_entry_tags(self, entry, tags):
|
||||
"""
|
||||
POST /api/entries/{entry}/tags.{_format}
|
||||
|
||||
POST /api/entries/{entry}/tags.{_format}
|
||||
Add one or more tags to an entry
|
||||
|
||||
Add one or more tags to an entry
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:param tags: string
|
||||
:return result
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:param tags: string
|
||||
:return result
|
||||
"""
|
||||
params = {'access_token': self.token, 'tags': []}
|
||||
if len(tags) > 0 and ',' in tags:
|
||||
@@ -387,28 +370,26 @@ class Wallabag(object):
|
||||
|
||||
async def delete_entry_tag(self, entry, tag):
|
||||
"""
|
||||
DELETE /api/entries/{entry}/tags/{tag}.{_format}
|
||||
|
||||
DELETE /api/entries/{entry}/tags/{tag}.{_format}
|
||||
Permanently remove one tag for an entry
|
||||
|
||||
Permanently remove one tag for an entry
|
||||
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:param tag: string The Tag
|
||||
:return data related to the ext
|
||||
:param entry: \w+ an integer The Entry ID
|
||||
:param tag: string The Tag
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/entries/{entry}/tags/{tag}.{ext}'.format(
|
||||
entry=entry, tag=tag, ext=self.format)
|
||||
return await self.query(url, "delete", **params)
|
||||
|
||||
async def get_tags(self, session):
|
||||
async def get_tags(self):
|
||||
"""
|
||||
GET /api/tags.{_format}
|
||||
|
||||
GET /api/tags.{_format}
|
||||
Retrieve all tags
|
||||
|
||||
Retrieve all tags
|
||||
|
||||
:return data related to the ext
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
path = '/api/tags.{ext}'.format(ext=self.format)
|
||||
@@ -416,13 +397,12 @@ class Wallabag(object):
|
||||
|
||||
async def delete_tag(self, tag):
|
||||
"""
|
||||
DELETE /api/tags/{tag}.{_format}
|
||||
|
||||
DELETE /api/tags/{tag}.{_format}
|
||||
Permanently remove one tag from every entry
|
||||
|
||||
Permanently remove one tag from every entry
|
||||
|
||||
:param tag: string The Tag
|
||||
:return data related to the ext
|
||||
:param tag: string The Tag
|
||||
:return data related to the ext
|
||||
"""
|
||||
path = '/api/tags/{tag}.{ext}'.format(tag=tag, ext=self.format)
|
||||
params = {'access_token': self.token}
|
||||
@@ -430,15 +410,13 @@ class Wallabag(object):
|
||||
|
||||
async def delete_tag_label(self, tag):
|
||||
"""
|
||||
DELETE /api/tag/label.{_format}
|
||||
|
||||
DELETE /api/tag/label.{_format}
|
||||
Permanently remove one tag from every entry.
|
||||
|
||||
Permanently remove one tag from every entry.
|
||||
|
||||
:param tag: string The Tag
|
||||
:return data related to the ext
|
||||
:param tag: string The Tag
|
||||
:return data related to the ext
|
||||
"""
|
||||
# @TODO check if that method is well documented as its the same as delete_tags !
|
||||
path = '/api/tag/label.{ext}'.format(ext=self.format)
|
||||
params = {'access_token': self.token,
|
||||
'tag': tag}
|
||||
@@ -446,15 +424,13 @@ class Wallabag(object):
|
||||
|
||||
async def delete_tags_label(self, tags):
|
||||
"""
|
||||
DELETE /api/tags/label.{_format}
|
||||
|
||||
DELETE /api/tags/label.{_format}
|
||||
Permanently remove some tags from every entry.
|
||||
|
||||
Permanently remove some tags from every entry.
|
||||
|
||||
:param tags: string tags as strings (comma splitted)
|
||||
:return data related to the ext
|
||||
:param tags: string tags as strings (comma splitted)
|
||||
:return data related to the ext
|
||||
"""
|
||||
# @TODO check if that method is well documented as its the same as delete_tags !
|
||||
path = '/api/tag/label.{ext}'.format(ext=self.format)
|
||||
params = {'access_token': self.token,
|
||||
'tags': tags}
|
||||
@@ -463,15 +439,14 @@ class Wallabag(object):
|
||||
# ANNOTATIONS
|
||||
async def delete_annotations(self, annotation):
|
||||
"""
|
||||
DELETE /api/annotations/{annotation}.{_format}
|
||||
|
||||
DELETE /api/annotations/{annotation}.{_format}
|
||||
Removes an annotation.
|
||||
|
||||
Removes an annotation.
|
||||
:param annotation \w+ string The annotation ID
|
||||
|
||||
:param annotation \w+ string The annotation ID
|
||||
|
||||
Will returns annotation for this entry
|
||||
:return data related to the ext
|
||||
Will returns annotation for this entry
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/annotations/{annotation}.{ext}'.format(
|
||||
@@ -480,15 +455,14 @@ class Wallabag(object):
|
||||
|
||||
async def put_annotations(self, annotation):
|
||||
"""
|
||||
PUT /api/annotations/{annotation}.{_format}
|
||||
|
||||
PUT /api/annotations/{annotation}.{_format}
|
||||
Updates an annotation.
|
||||
|
||||
Updates an annotation.
|
||||
:param annotation \w+ string The annotation ID
|
||||
|
||||
:param annotation \w+ string The annotation ID
|
||||
|
||||
Will returns annotation for this entry
|
||||
:return data related to the ext
|
||||
Will returns annotation for this entry
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/annotations/{annotation}.{ext}'.format(
|
||||
@@ -497,15 +471,14 @@ class Wallabag(object):
|
||||
|
||||
async def get_annotations(self, entry):
|
||||
"""
|
||||
GET /api/annotations/{entry}.{_format}
|
||||
|
||||
GET /api/annotations/{entry}.{_format}
|
||||
Retrieve annotations for an entry
|
||||
|
||||
Retrieve annotations for an entry
|
||||
:param entry \w+ integer The entry ID
|
||||
|
||||
:param entry \w+ integer The entry ID
|
||||
|
||||
Will returns annotation for this entry
|
||||
:return data related to the ext
|
||||
Will returns annotation for this entry
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/annotations/{entry}.{ext}'.format(entry=entry,
|
||||
@@ -514,14 +487,13 @@ class Wallabag(object):
|
||||
|
||||
async def post_annotations(self, entry, **kwargs):
|
||||
"""
|
||||
POST /api/annotations/{entry}.{_format}
|
||||
|
||||
POST /api/annotations/{entry}.{_format}
|
||||
Creates a new annotation.
|
||||
|
||||
Creates a new annotation.
|
||||
:param entry \w+ integer The entry ID
|
||||
|
||||
:param entry \w+ integer The entry ID
|
||||
|
||||
:return
|
||||
:return
|
||||
"""
|
||||
params = dict({'access_token': self.token,
|
||||
'ranges': [],
|
||||
@@ -542,12 +514,11 @@ class Wallabag(object):
|
||||
@property
|
||||
async def version(self):
|
||||
"""
|
||||
GET /api/version.{_format}
|
||||
|
||||
GET /api/version.{_format}
|
||||
Retrieve version number
|
||||
|
||||
Retrieve version number
|
||||
|
||||
:return data related to the ext
|
||||
:return data related to the ext
|
||||
"""
|
||||
params = {'access_token': self.token}
|
||||
url = '/api/version.{ext}'.format(ext=self.format)
|
||||
@@ -556,6 +527,9 @@ class Wallabag(object):
|
||||
@classmethod
|
||||
async def get_token(cls, host, **params):
|
||||
"""
|
||||
POST /oauth/v2/token
|
||||
|
||||
Get a new token
|
||||
|
||||
:param host: host of the service
|
||||
:param params: will contain :
|
||||
@@ -574,4 +548,3 @@ class Wallabag(object):
|
||||
async with sess.post(host + path, data=params) as resp:
|
||||
data = await cls.handle_json_response(resp)
|
||||
return data.get("access_token")
|
||||
|
||||
|
||||
Reference in New Issue
Block a user