Improve docs for Python noobs

[pablomendes]

Hey there! Thanks for writing this client. I would like to kindly ask for some help.

I do not know Python. I have been trying following instructions on the front page.

>>> import spotlight
>>> annotations = spotlight.annotate('localhost:2222/rest/annotate','parallel computing',confidence='0',support='0')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "spotlight/__init__.py", line 154, in annotate
    response.raise_for_status()
  File "/usr/local/lib/python2.6/dist-packages/requests/models.py", line 519, in raise_for_status
    raise self.error
urllib2.URLError: <urlopen error unknown url type: localhost>

Figured there must be an http>// missing, so tried:

>>> annotations = spotlight.annotate('http://localhost:2222/rest/annotate','Parallel Computing',confidence='0',support='0')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "spotlight/__init__.py", line 157, in annotate
    pydict = json.loads(response.text)
AttributeError: 'Response' object has no attribute 'text'

With curl:

$ curl -H "accept: application/json" http://spotlight.dbpedia.org/rest/annotate --data "text=Parallel Computing&confidence=0&support=0"

{
  "@text": "Parallel Computing",
  "@confidence": "0.0",
  "@support": "0",
  "@types": "",
  "@sparql": "",
  "@policy": "whitelist",
  "Resources": [  {
    "@URI": "http://dbpedia.org/resource/Parallel_computing",
    "@support": "365",
    "@types": "Freebase:/conferences/conference_subject,Freebase:/conferences,Freebase:/computer/programming_language_paradigm,Freebase:/computer,DBpedia:TopicalConcept",
    "@surfaceForm": "Parallel Computing",
    "@offset": "0",
    "@similarityScore": "0.3197186589241028",
    "@percentageOfSecondRank": "-1.0"
  }]
}

What gives?

Cheers, Pablo

[originell]

Hey :)

Oh interesting. Would you mind providing me with your python and dbpedia version?

Here at newsgrape we are currently running python 2.6 and dbpedia 0.5 flawlessly. So, are you running a newer dbpedia version – usually python versions are not a problem (except when it's 3+) ?

Anyways will try to reproduce this on the morrow :) Thanks for your report! This will come in handy in the test suite I hope ;-)

[pablomendes]

$ python --version Python 2.6.5

DBpedia Spotlight is version 0.6.5 https://github.com/dbpedia-spotlight/dbpedia-spotlight/downloads

[originell]

I just updated the code a bit and rewrote parts of the README. Would you mind testing it? I can't really reproduce the response.text exception you mentioned above.

If you don't have it installed, you will probably need pip, for easy requirements installation. From the commandline:

sudo easy_install pip

easy_install is a utility which downloads packages from the Python Package Index (short: pypi, not to be mixed up with pypy). However it has some kinks and pip is generally the preferred way to install from pypi. Pip can do a lot more, but that is another topic :) I think Java equivalents to this might be maven and/or leiningen.

Before we march on into pyspotlight, I highly recommend installing ipython, which is an enhanced version of the default interactive shell (has some color, code completion and many many more features…). Having ipython on a system-wide basis is nothing to be ashamed of.

sudo pip install ipython

Note: for the sake of simplicity I recommend we do the rest on a system-wide basis too. If you feel uncomfortable with this, please refer to virtualenv, which is a way to create completely isolated python environments. Basically virtualenv is something every serious pythonista knows and uses because you can keep multiple different python versions and packages isolated from each other on a per-project/app basis. Guess it is in some ways similar to Java's CLASS_PATH, but in others entirely different hehe.

Then just get a fresh git HEAD from this repository. Inside the cloned pyspotlight/ directory you'll find a requirements.txt. Here we'll use pip:

sudo pip install -r requirements.txt

that should install everything needed. Then, from the same directory, please repeat your session from the initial issue description (and don't forget to use ipython instead of python! <3 :D)

[originell]

By the way, the curl method from above is done with the server running on the dbpedia domain. Is it guaranteed to always run the latest version (so 0.6.5 now)?

[pablomendes]

Much better error handling. Works fine now.

The server at spotlight.dbpedia.org is running 0.6.5 now.

It is not guaranteed to always run the latest. Every time the server is upgraded, an announcement message is sent to dbp-spotlight-users.

[pablomendes]

Oh, and thanks much! :)

[originell]

As always a pleasure :)