include a setup.py
zvodd opened this issue · comments
that way the module can be installed via pip
Hi @zvodd,
Saw the tweet before you deleted it, Would have loved you to contrib or at least had a beer but in either case check this branch out and see what you think then ill merge into master and update the README.
My original tweet referred to the module repository that I found by
navigating to the python code example linked in the api docs, which I later
realised was not the official API. In light of discovering the real api
module, I realised the tweet was not relevant. Although after fighting with
the real API module, I now have some more useful criticisms.
Whilst the pain of using the library is still fresh in my mind, please
excuse the harsh tone. I do understand designing an easy to use API can be
extremely difficult and my perspective is largely shaped by my exposure to
amazingly well built python modules. Most of them having the benefit of
many years of great contributions from truly expert python programmers and
not being held accountable to corporate deadlines.
The documentation on the telstra dev site points to old non working code
examples for python. Once I found the "working" API module, even though it
is documented, it is only really documented in that the API calls and
arguments are listed. A lot of "what", not much "why" or "how". The
practical use of the API isn't well documented - i.e. It doesn't mention
the need to provision numbers before accessing the SMS API. Creating
context handlers for various parts of the API (like the various "clients",)
could really improve usability.
It doesn't look anything like a python module should, more closely
resembling Java library attempting to be implemented in python. Most of the
objects are python classes used as key -> value maps, but with the added
bonus of jumping through hoops to enumerate. If these were just
dictionaries, it would be easier to debug, use and understand them. Though
there are other ways to implement these classes that would be nicer.
Custom exceptions HIDE real error messages! These exceptions are
cryptically and verbosely named things like
"ErrorErrorErrorErrorException". I have never seen so many custom
exceptions named so badly in a python module.
Getting into the specific case of trying to access the SMS API before
provisioning the number, the returned error message from
"ErrorErrorErrorErrorException" was "url not found" with a status code 401
(or 400?) . I had to catch and write an exception handler that actually
read the REAL error message that is in the http response that actually
tells you what was wrong - basically "SMS number not Provisioned". The
error message was actually in the response, SMS client class (or is it the
http wrapper?) just returns a message based on the http status code, even
though most would return a JSON payload with an error description! The
sourness of this is that these custom exceptions appear to actually have
code in them find the real error message, but the exceptions are not used
in way to make use of the code.
Another sore point is that the modules repository is laid out in a way that
the module can't be referenced by url for pip to install it. Instead one
has to manually download the repo and then install from the local
directory. Just putting the setup.py in the top level of the repo and a
tiny bit of refactoring would resolve this. This is nearly universally done
for python modules hosted on git repositories and allows a
"requirements.txt" file to have an entry like "git+
https://github.com/telstra/MessagingAPI-SDK-python.git".
…On 29 November 2017 at 04:25, developersteve ***@***.***> wrote:
Hi @zvodd <https://github.com/zvodd>,
Saw the tweet before you deleted it, Would have loved you to contrib or at
least had a beer but in either case check this branch out and see what you
think then ill merge into master and update the README.
https://github.com/telstra/MessagingAPI-SDK-python/tree/pip
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AApySSDwC9cNukeU8EYjd2E_qIWHAYVeks5s7GwogaJpZM4Qtm4K>
.