Skip to content

Commit a2705a2

Browse files
six519six519
committed
finished code documentation
1 parent 8e03ce7 commit a2705a2

5 files changed

Lines changed: 112 additions & 10 deletions

File tree

‎pastebin_python/pastebin.py‎

Lines changed: 84 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,13 @@
55
.. moduleauthor:: Ferdinand Silva <ferdinandsilva@ferdinandsilva.com>
66
77
"""
8-
import re, urllib2, urllib
8+
import re
9+
import urllib2
10+
import urllib
911
from xml.dom.minidom import parseString
10-
11-
from pastebin_options import OPTION_PASTE, OPTION_LIST, \
12-
OPTION_TRENDS, OPTION_DELETE, \
13-
OPTION_USER_DETAILS
14-
12+
from pastebin_options import OPTION_PASTE, OPTION_LIST, OPTION_TRENDS, OPTION_DELETE, OPTION_USER_DETAILS
1513
from pastebin_constants import PASTEBIN_API_POST_URL, PASTEBIN_API_LOGIN_URL
16-
from pastebin_exceptions import PastebinBadRequestException, PastebinNoPastesException, \
17-
PastebinFileException
14+
from pastebin_exceptions import PastebinBadRequestException, PastebinNoPastesException, PastebinFileException
1815

1916
class PastebinPython(object):
2017
"""This is the main class to be instantiated to use pastebin.com functionality
@@ -44,7 +41,7 @@ def __init__(self, **kwargs):
4441

4542
@property
4643
def api_user_key(self):
47-
"""This is where the api_user_key is stored after calling :func:`getUserKey`
44+
"""This is where the api_user_key is stored after calling :func:`creatAPIUserKey`
4845
4946
:returns: str -- the api_user_key
5047
@@ -151,7 +148,21 @@ def __processPost(self, url, data):
151148

152149
return response
153150

154-
def getUserKey(self, api_user_name, api_user_password):
151+
def creatAPIUserKey(self, api_user_name, api_user_password):
152+
"""This is used to request an *api_user_key* which can be used to create a paste as a logged in user
153+
154+
:param api_user_name: this is the pastebin.com username
155+
:type api_user_name: str
156+
:param api_user_password: this is the pastebin.com password
157+
:type api_user_password: str
158+
:returns: str -- unique user session key
159+
:raises: PastebinBadRequestException
160+
161+
.. note::
162+
163+
If successfull the unique user session key will be assigned to the private variable *__api_user_key* and can be get with the property *api_user_key*
164+
165+
"""
155166

156167
postData = {
157168
'api_dev_key':self.api_dev_key,
@@ -164,6 +175,19 @@ def getUserKey(self, api_user_name, api_user_password):
164175
return self.__api_user_key
165176

166177
def listUserPastes(self, api_results_limit=50):
178+
"""This will list pastes created by a user
179+
180+
:param api_results_limit: this is not required but the min value should be 1 and the max value should be 1000
181+
:type api_results_limit: int
182+
:returns: list -- the list of of pastes in a dictionary type
183+
:raises: PastebinBadRequestException, PastebinNoPastesException
184+
185+
.. note::
186+
187+
Need to call the :func:`creatAPIUserKey` first before calling this function
188+
Pastes list will be stored to the private variable *__api_user_paste_list* and can be retrieve by the property *api_user_key*
189+
190+
"""
167191

168192
postData = {
169193
'api_dev_key':self.api_dev_key,
@@ -178,6 +202,12 @@ def listUserPastes(self, api_results_limit=50):
178202
return self.__api_user_paste_list
179203

180204
def listTrendingPastes(self):
205+
"""This will list the 18 currently trending pastes
206+
207+
:returns: list -- the 18 currently trending pastes in a dictionary format
208+
:raises: PastebinBadRequestException
209+
210+
"""
181211

182212
postData = {
183213
'api_dev_key':self.api_dev_key,
@@ -190,6 +220,13 @@ def listTrendingPastes(self):
190220
return trendsList
191221

192222
def __parseUser(self, xmlString):
223+
"""This will parse the xml string returned by the function :func:`getUserInfos`
224+
225+
:param xmlString: this is the returned xml string from :func:`getUserInfos`
226+
:type xmlString: str
227+
:returns: list -- user info in a dictionary format
228+
229+
"""
193230
retList = []
194231
userElements = xmlString.getElementsByTagName('user')
195232

@@ -208,6 +245,13 @@ def __parseUser(self, xmlString):
208245
return retList
209246

210247
def __parsePaste(self, xmlString):
248+
"""This will parse the xml string returned by the the function :func:`listUserPastes` or :func:`listTrendingPastes`
249+
250+
:param xmlString: this is the returned xml string from :func:`listUserPastes` or :func:`listTrendingPastes`
251+
:type xmlString: str
252+
:returns: list -- pastes info in a dictionary format
253+
254+
"""
211255
retList = []
212256
pasteElements = xmlString.getElementsByTagName('paste')
213257

@@ -235,6 +279,15 @@ def __parsePaste(self, xmlString):
235279

236280

237281
def __parseXML(self, xml, isPaste=True):
282+
"""This will handle all of the xml string parsing
283+
284+
:param xml: xml string
285+
:type xml: str
286+
:param isPaste: if True then it will parse the pastes info else it will parse the user info
287+
:type isPaste: bool
288+
:returns: list -- info in a dictionary format
289+
290+
"""
238291
retList = []
239292
xmlString = parseString("<pasteBin>%s</pasteBin>" % xml)
240293

@@ -247,6 +300,17 @@ def __parseXML(self, xml, isPaste=True):
247300

248301

249302
def deletePaste(self, api_paste_key):
303+
"""This will delete pastes created by certain users
304+
305+
:param api_paste_key: this is the paste key that which you can get in the :func:`listUserPastes` function
306+
:type api_paste_key: str
307+
:returns: bool -- True if the deletion is successfull else False
308+
309+
.. note::
310+
311+
Before calling this function, you need to call the :func:`creatAPIUserKey` first then call the :func:`listUserPastes`
312+
313+
"""
250314
postData = {
251315
'api_dev_key':self.api_dev_key,
252316
'api_user_key':self.api_user_key,
@@ -266,6 +330,16 @@ def deletePaste(self, api_paste_key):
266330

267331

268332
def getUserInfos(self):
333+
"""You can obtain a users personal info and certain settings by calling this function
334+
335+
:returns: list -- user info in a dictionary format
336+
:raises: PastebinBadRequestException
337+
338+
.. note::
339+
340+
You need to call the :func:`creatAPIUserKey` before calling this function
341+
342+
"""
269343

270344
postData = {
271345
'api_dev_key':self.api_dev_key,

‎pastebin_python/pastebin_constants.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
"""
2+
.. module:: pastebin_constants
3+
:sypnosis: This module contains the constants that can be used in the :func:`pastebin_python.pastebin.PastebinPython.__processPost` , :func:`pastebin_python.pastebin.PastebinPython.createPaste` and :func:`pastebin_python.pastebin.PastebinPython.createPasteFromFile`
4+
5+
.. moduleauthor:: Ferdinand Silva <ferdinandsilva@ferdinandsilva.com>
6+
7+
"""
18
PASTEBIN_API_URL = "http://pastebin.com/api/"
29
PASTEBIN_API_POST_URL = "%s%s" % (PASTEBIN_API_URL, "api_post.php")
310
PASTEBIN_API_LOGIN_URL = "%s%s" % (PASTEBIN_API_URL, "api_login.php")

‎pastebin_python/pastebin_exceptions.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
"""
2+
.. module:: pastebin_exceptions
3+
:sypnosis: This module contains all of the exceptions
4+
5+
.. moduleauthor:: Ferdinand Silva <ferdinandsilva@ferdinandsilva.com>
6+
7+
"""
18
class PastebinBadRequestException(Exception):
29
pass
310

‎pastebin_python/pastebin_formats.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
"""
2+
.. module:: pastebin_formats
3+
:sypnosis: This module contains constants that can be used in :func:`pastebin_python.pastebin.PastebinPython.createPaste` or :func:`pastebin_python.pastebin.PastebinPython.createPasteFromFile` in *api_paste_format* parameter
4+
5+
.. moduleauthor:: Ferdinand Silva <ferdinandsilva@ferdinandsilva.com>
6+
7+
"""
18
FORMAT_4CS = "4cs"
29
FORMAT_6502_ACME_CROSS_ASSEMBLER = "6502acme"
310
FORMAT_6502_KICK_ASSEMBLER = "6502kickass"

‎pastebin_python/pastebin_options.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
"""
2+
.. module:: pastebin_options
3+
:sypnosis: This module contains constants that can be used in *api_option*
4+
5+
.. moduleauthor:: Ferdinand Silva <ferdinandsilva@ferdinandsilva.com>
6+
7+
"""
18
OPTION_PASTE = "paste"
29
OPTION_LIST = "list"
310
OPTION_TRENDS = "trends"

0 commit comments

Comments
 (0)