add a .first method to RecordCollections

[chadwhitacre]

It's a common use-case to want one and only one result from a query.

[chadwhitacre]

Includes #42.

[chadwhitacre]

Rebased to fix a broken test in the appropriate commit, previous head was dcb9e7a.

[chadwhitacre]

499fd5b allows for passing in an exception as default and having that be raised for you. Not sure if you'll want that feature even if you want the rest of the PR.

[chadwhitacre]

Ready for review, @kennethreitz. :)

[kennethreitz]

So, I have mixed feelings about this one.

Currently, you can get this behavior with rows[0] (get just the first row), or rows[0:1].all(as_dict=True).
I do see some API symmetry between one & all, however.

I tend to lean on the side of introducing as few methods as possible to an API, and adding only what is necessary. This does seem like a good nice-to-have, though.

I am torn.

[kennethreitz]

This could be simplified to simply use use

record = self[0]

[chadwhitacre]

Done in 5e60bb9.

[chadwhitacre]

Rebased on master at dd44086. Previous head was 5e60bb9.

[chadwhitacre]

Currently, you can get this behavior with rows[0] (get just the first row), or rows[0:1].all(as_dict=True).

Yes, but quite often it should be a bug if there's more than one result, and/or not a bug if there's less than one. The purpose of the one method is to provide this error checking and defaulting.

I am torn.

Well, it's here if you want it. :-)

[Brobin]

Would first be a better name? It's a little more specific to which one you are retrieving, and similar to other DB/ORM Api's I've seen before.

user = db.query('select * from users where id=1').first()

I do agree that just doing rows[0] is already pretty easy, and it's not that difficult.

[chadwhitacre]

first makes it sound like you're expecting more than one, and you just want the first one, in which case there's not much advantage over rows[0].

one suggests that for the query to return more than one result is a bug.

[Brobin]

Ah, gotcha. I didn't realize you were checking if there was more than one record.

[chadwhitacre]

And also defaulting if there's less than one. :)

[kennethreitz]

@Brobin that was what I thought too. That's one of the main reasons I'm not gung ho about adding this — I think it's confusing :)

RecordCollection.exactly_one() on the other hand, hahaha.

[Brobin]

RecordSet.exactly_one_and_fail_if_there_are_more() 😜

[kennethreitz]

I think .first() is what I want, and would be nice to have. It would return None if none exists, I think.

this needs a rebase if we wish to proceed ;)

[chadwhitacre]

Rebased on master at 9e65833. Previous head was a49d1ff. Renaming to first ... :-)

[chadwhitacre]

No CI? I will run tests locally ...

[chadwhitacre]

85fbec7

(env) $ py.test tests/
============================================ test session starts =============================================
platform darwin -- Python 3.5.0, pytest-2.8.7, py-1.4.31, pluggy-0.3.1
rootdir: /Users/whit537, inifile: pytest.ini
collected 15 items 

tests/test_records.py .............
tests/test_transactions.py ..

========================================= 15 passed in 1.47 seconds ==========================================
(env) $

[chadwhitacre]

3b7438f

(env) $ py.test tests/
============================================ test session starts =============================================
platform darwin -- Python 3.5.0, pytest-2.8.7, py-1.4.31, pluggy-0.3.1
rootdir: /Users/whit537, inifile: pytest.ini
collected 15 items 

tests/test_records.py .............
tests/test_transactions.py ..

========================================= 15 passed in 1.42 seconds ==========================================
(env) $

[chadwhitacre]

Alright, @kennethreitz, lemme know if you want a squash or further changes or whatevs. :-)

[kennethreitz]

✨🍰✨