first-2.0.0/0000755000076500000240000000000012036224256013103 5ustar hynekstaff00000000000000first-2.0.0/AUTHORS.rst0000644000076500000240000000022712036067101014755 0ustar hynekstaff00000000000000Credits ======= “first” is written and maintained by Hynek Schlawack and various contributors: - Łukasz Langa - Nick Coghlan - Vincent Driessen first-2.0.0/first.egg-info/0000755000076500000240000000000012036224256015724 5ustar hynekstaff00000000000000first-2.0.0/first.egg-info/dependency_links.txt0000644000076500000240000000000112036224255021771 0ustar hynekstaff00000000000000 first-2.0.0/first.egg-info/PKG-INFO0000644000076500000240000001543612036224255017031 0ustar hynekstaff00000000000000Metadata-Version: 1.1 Name: first Version: 2.0.0 Summary: Return the first true value of an iterable. Home-page: http://github.com/hynek/first/ Author: Hynek Schlawack Author-email: hs@ox.cx License: MIT Description: first: The function you always missed in Python =============================================== *first* is a MIT licensed Python package with a simple function that returns the first true value from an iterable, or ``None`` if there is none. If you need more power, you can also supply a ``key`` function that is used to judge the truth value of the element or a ``default`` value if ``None`` doesn’t fit your use case. I’m using the term “true” consistently with Python docs for ``any()`` and ``all()`` — it means that the value evaluates to true like: ``True``, ``1``, ``"foo"`` or ``[None]``. But **not**: ``None``, ``False`` or ``0``. In JavaScript, they call this “truthy”. Examples ======== A simple example to get started: :: >>> from first import first >>> first([0, None, False, [], (), 42]) 42 However, it’s especially useful for dealing with regular expressions in ``if/elif/else`` branches: :: import re from first import first re1 = re.compile('b(.*)') re2 = re.compile('a(.*)') m = first(regexp.match('abc') for regexp in [re1, re2]) if not m: print('no match!') elif m.re is re1: print('re1', m.group(1)) elif m.re is re2: print('re2', m.group(1)) The optional ``key`` function gives you even *more* selection power. If you want to return the first even number from a list, just do the following:: >>> from first import first >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0) 4 ``default`` on the other hand allows you to specify a value that is returned if none of the elements is true: :: >>> from first import first >>> first([0, None, False, [], ()], default=42) 42 Usage ===== The package consists of one module consisting of one function:: from first import first first(iterable, default=None, key=None) This function returns the first element of ``iterable`` that is true if ``key`` is ``None``. If there is no true element, the value of ``default`` is returned, which is ``None`` by default. If a callable is supplied in ``key``, the result of ``key(element)`` is used to judge the truth value of the element, but the element itself is returned. *first* has no dependencies and should work with any Python available. Of course, it works with the awesome `Python 3`_ everybody should be using. Alternatives ============ *first* brings nothing to the table that wasn’t possible before. However the existing solutions aren’t very idiomatic for such a common and simple problem. The following constructs are equivalent to ``first(seq)`` and work since Python 2.6: :: next(itertools.ifilter(None, seq), None) next(itertools.ifilter(bool, seq), None) next((x for x in seq if x), None) None of them is as pretty as I’d like them to be. The ``re`` example from above would look like the following: :: next(itertools.ifilter(None, (regexp.match('abc') for regexp in [re1, re2])), None) next((regexp.match('abc') for regexp in [re1, re2] if regexp.match('abc')), None) Note that in the second case you have to call ``regexp.match()`` *twice*. For comparison, one more time the *first*-version: :: first(regexp.match('abc') for regexp in [re1, re2]) Idiomatic, clear and readable. Pythonic. :) Background ========== The idea for *first* goes back to a discussion I had with `Łukasz Langa`_ about how the ``re`` example above is painful in Python. We figured such a function is missing Python, however it’s rather unlikely we’d get it in and even if, it wouldn’t get in before 3.4 anyway, which is years away as of yours truly is writing this. So I decided to release it as a package for now. If it proves popular enough, it may even make it into Python’s stdlib in the end. .. _`Python 3`: http://getpython3.com/ .. _`Łukasz Langa`: https://github.com/ambv History ======= 2.0.0 (2012-10-13) ------------------ - `pred` proved to be rather useless. Changed to `key` which is just a selector. This is a *backward incompatible* change and the reason for going 2.0. - Add `default` argument which is returned instead of `None` if no true element is found. 1.0.2 (2012-10-09) ------------------ - Fix packaging. I get this never right the first time. :-/ 1.0.1 (2012-10-09) ------------------ - Documentation fixes only. 1.0.0 (2012-10-09) ------------------ - Initial release. Credits ======= “first” is written and maintained by Hynek Schlawack and various contributors: - Łukasz Langa - Nick Coghlan - Vincent Driessen Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Natural Language :: English Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.3 Classifier: Programming Language :: Python :: 2.4 Classifier: Programming Language :: Python :: 2.5 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.0 Classifier: Programming Language :: Python :: 3.1 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Topic :: Software Development :: Libraries :: Python Modules first-2.0.0/first.egg-info/SOURCES.txt0000644000076500000240000000027412036224256017613 0ustar hynekstaff00000000000000AUTHORS.rst HISTORY.rst LICENSE MANIFEST.in README.rst first.py setup.py first.egg-info/PKG-INFO first.egg-info/SOURCES.txt first.egg-info/dependency_links.txt first.egg-info/top_level.txtfirst-2.0.0/first.egg-info/top_level.txt0000644000076500000240000000000612036224255020451 0ustar hynekstaff00000000000000first first-2.0.0/first.py0000644000076500000240000000327612036072021014603 0ustar hynekstaff00000000000000## -*- coding: utf-8 -*- """ first ===== first is the function you always missed in Python. In the simplest case, it returns the first true element from an iterable: >>> from first import first >>> first([0, False, None, [], (), 42]) 42 Or None if there is none: >>> from first import first >>> first([]) is None True >>> first([0, False, None, [], ()]) is None True It also supports the passing of a key argument to help selecting the first match in a more advanced way. >>> from first import first >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0) 4 :copyright: (c) 2012 by Hynek Schlawack. :license: MIT, see LICENSE for more details. """ __title__ = 'first' __version__ = '2.0.0' __author__ = 'Hynek Schlawack' __license__ = 'MIT' __copyright__ = 'Copyright 2012 Hynek Schlawack' def first(iterable, default=None, key=None): """ Return first element of `iterable` that evaluates true, else return None (or an optional default value). >>> first([0, False, None, [], (), 42]) 42 >>> first([0, False, None, [], ()]) is None True >>> first([0, False, None, [], ()], default='ohai') 'ohai' >>> import re >>> m = first(re.match(regex, 'abc') for regex in ['b.*', 'a(.*)']) >>> m.group(1) 'bc' The optional `key` argument specifies a one-argument predicate function like that used for `filter()`. The `key` argument, if supplied, must be in keyword form. For example: >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0) 4 """ if key is None: for el in iterable: if el: return el else: for el in iterable: if key(el): return el return default first-2.0.0/HISTORY.rst0000644000076500000240000000105112036223530014765 0ustar hynekstaff00000000000000History ======= 2.0.0 (2012-10-13) ------------------ - `pred` proved to be rather useless. Changed to `key` which is just a selector. This is a *backward incompatible* change and the reason for going 2.0. - Add `default` argument which is returned instead of `None` if no true element is found. 1.0.2 (2012-10-09) ------------------ - Fix packaging. I get this never right the first time. :-/ 1.0.1 (2012-10-09) ------------------ - Documentation fixes only. 1.0.0 (2012-10-09) ------------------ - Initial release. first-2.0.0/LICENSE0000644000076500000240000000204312033004131014070 0ustar hynekstaff00000000000000Copyright (c) 2012 Hynek Schlawack Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. first-2.0.0/MANIFEST.in0000644000076500000240000000007412036224122014632 0ustar hynekstaff00000000000000include README.rst AUTHORS.rst LICENSE HISTORY.rst first.py first-2.0.0/PKG-INFO0000644000076500000240000001543612036224256014211 0ustar hynekstaff00000000000000Metadata-Version: 1.1 Name: first Version: 2.0.0 Summary: Return the first true value of an iterable. Home-page: http://github.com/hynek/first/ Author: Hynek Schlawack Author-email: hs@ox.cx License: MIT Description: first: The function you always missed in Python =============================================== *first* is a MIT licensed Python package with a simple function that returns the first true value from an iterable, or ``None`` if there is none. If you need more power, you can also supply a ``key`` function that is used to judge the truth value of the element or a ``default`` value if ``None`` doesn’t fit your use case. I’m using the term “true” consistently with Python docs for ``any()`` and ``all()`` — it means that the value evaluates to true like: ``True``, ``1``, ``"foo"`` or ``[None]``. But **not**: ``None``, ``False`` or ``0``. In JavaScript, they call this “truthy”. Examples ======== A simple example to get started: :: >>> from first import first >>> first([0, None, False, [], (), 42]) 42 However, it’s especially useful for dealing with regular expressions in ``if/elif/else`` branches: :: import re from first import first re1 = re.compile('b(.*)') re2 = re.compile('a(.*)') m = first(regexp.match('abc') for regexp in [re1, re2]) if not m: print('no match!') elif m.re is re1: print('re1', m.group(1)) elif m.re is re2: print('re2', m.group(1)) The optional ``key`` function gives you even *more* selection power. If you want to return the first even number from a list, just do the following:: >>> from first import first >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0) 4 ``default`` on the other hand allows you to specify a value that is returned if none of the elements is true: :: >>> from first import first >>> first([0, None, False, [], ()], default=42) 42 Usage ===== The package consists of one module consisting of one function:: from first import first first(iterable, default=None, key=None) This function returns the first element of ``iterable`` that is true if ``key`` is ``None``. If there is no true element, the value of ``default`` is returned, which is ``None`` by default. If a callable is supplied in ``key``, the result of ``key(element)`` is used to judge the truth value of the element, but the element itself is returned. *first* has no dependencies and should work with any Python available. Of course, it works with the awesome `Python 3`_ everybody should be using. Alternatives ============ *first* brings nothing to the table that wasn’t possible before. However the existing solutions aren’t very idiomatic for such a common and simple problem. The following constructs are equivalent to ``first(seq)`` and work since Python 2.6: :: next(itertools.ifilter(None, seq), None) next(itertools.ifilter(bool, seq), None) next((x for x in seq if x), None) None of them is as pretty as I’d like them to be. The ``re`` example from above would look like the following: :: next(itertools.ifilter(None, (regexp.match('abc') for regexp in [re1, re2])), None) next((regexp.match('abc') for regexp in [re1, re2] if regexp.match('abc')), None) Note that in the second case you have to call ``regexp.match()`` *twice*. For comparison, one more time the *first*-version: :: first(regexp.match('abc') for regexp in [re1, re2]) Idiomatic, clear and readable. Pythonic. :) Background ========== The idea for *first* goes back to a discussion I had with `Łukasz Langa`_ about how the ``re`` example above is painful in Python. We figured such a function is missing Python, however it’s rather unlikely we’d get it in and even if, it wouldn’t get in before 3.4 anyway, which is years away as of yours truly is writing this. So I decided to release it as a package for now. If it proves popular enough, it may even make it into Python’s stdlib in the end. .. _`Python 3`: http://getpython3.com/ .. _`Łukasz Langa`: https://github.com/ambv History ======= 2.0.0 (2012-10-13) ------------------ - `pred` proved to be rather useless. Changed to `key` which is just a selector. This is a *backward incompatible* change and the reason for going 2.0. - Add `default` argument which is returned instead of `None` if no true element is found. 1.0.2 (2012-10-09) ------------------ - Fix packaging. I get this never right the first time. :-/ 1.0.1 (2012-10-09) ------------------ - Documentation fixes only. 1.0.0 (2012-10-09) ------------------ - Initial release. Credits ======= “first” is written and maintained by Hynek Schlawack and various contributors: - Łukasz Langa - Nick Coghlan - Vincent Driessen Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Natural Language :: English Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.3 Classifier: Programming Language :: Python :: 2.4 Classifier: Programming Language :: Python :: 2.5 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.0 Classifier: Programming Language :: Python :: 3.1 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Topic :: Software Development :: Libraries :: Python Modules first-2.0.0/README.rst0000644000076500000240000000742212036221235014571 0ustar hynekstaff00000000000000first: The function you always missed in Python =============================================== *first* is a MIT licensed Python package with a simple function that returns the first true value from an iterable, or ``None`` if there is none. If you need more power, you can also supply a ``key`` function that is used to judge the truth value of the element or a ``default`` value if ``None`` doesn’t fit your use case. I’m using the term “true” consistently with Python docs for ``any()`` and ``all()`` — it means that the value evaluates to true like: ``True``, ``1``, ``"foo"`` or ``[None]``. But **not**: ``None``, ``False`` or ``0``. In JavaScript, they call this “truthy”. Examples ======== A simple example to get started: :: >>> from first import first >>> first([0, None, False, [], (), 42]) 42 However, it’s especially useful for dealing with regular expressions in ``if/elif/else`` branches: :: import re from first import first re1 = re.compile('b(.*)') re2 = re.compile('a(.*)') m = first(regexp.match('abc') for regexp in [re1, re2]) if not m: print('no match!') elif m.re is re1: print('re1', m.group(1)) elif m.re is re2: print('re2', m.group(1)) The optional ``key`` function gives you even *more* selection power. If you want to return the first even number from a list, just do the following:: >>> from first import first >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0) 4 ``default`` on the other hand allows you to specify a value that is returned if none of the elements is true: :: >>> from first import first >>> first([0, None, False, [], ()], default=42) 42 Usage ===== The package consists of one module consisting of one function:: from first import first first(iterable, default=None, key=None) This function returns the first element of ``iterable`` that is true if ``key`` is ``None``. If there is no true element, the value of ``default`` is returned, which is ``None`` by default. If a callable is supplied in ``key``, the result of ``key(element)`` is used to judge the truth value of the element, but the element itself is returned. *first* has no dependencies and should work with any Python available. Of course, it works with the awesome `Python 3`_ everybody should be using. Alternatives ============ *first* brings nothing to the table that wasn’t possible before. However the existing solutions aren’t very idiomatic for such a common and simple problem. The following constructs are equivalent to ``first(seq)`` and work since Python 2.6: :: next(itertools.ifilter(None, seq), None) next(itertools.ifilter(bool, seq), None) next((x for x in seq if x), None) None of them is as pretty as I’d like them to be. The ``re`` example from above would look like the following: :: next(itertools.ifilter(None, (regexp.match('abc') for regexp in [re1, re2])), None) next((regexp.match('abc') for regexp in [re1, re2] if regexp.match('abc')), None) Note that in the second case you have to call ``regexp.match()`` *twice*. For comparison, one more time the *first*-version: :: first(regexp.match('abc') for regexp in [re1, re2]) Idiomatic, clear and readable. Pythonic. :) Background ========== The idea for *first* goes back to a discussion I had with `Łukasz Langa`_ about how the ``re`` example above is painful in Python. We figured such a function is missing Python, however it’s rather unlikely we’d get it in and even if, it wouldn’t get in before 3.4 anyway, which is years away as of yours truly is writing this. So I decided to release it as a package for now. If it proves popular enough, it may even make it into Python’s stdlib in the end. .. _`Python 3`: http://getpython3.com/ .. _`Łukasz Langa`: https://github.com/ambv first-2.0.0/setup.cfg0000644000076500000240000000007312036224256014724 0ustar hynekstaff00000000000000[egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 first-2.0.0/setup.py0000644000076500000240000000257012036067101014613 0ustar hynekstaff00000000000000from setuptools import setup import first setup( name='first', version=first.__version__, description='Return the first true value of an iterable.', long_description=(open('README.rst').read() + '\n\n' + open('HISTORY.rst').read() + '\n\n' + open('AUTHORS.rst').read()), url='http://github.com/hynek/first/', license=first.__license__, author=first.__author__, author_email='hs@ox.cx', py_modules=['first'], classifiers=[ 'Development Status :: 5 - Production/Stable', 'Intended Audience :: Developers', 'Natural Language :: English', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', 'Programming Language :: Python', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 2.3', 'Programming Language :: Python :: 2.4', 'Programming Language :: Python :: 2.5', 'Programming Language :: Python :: 2.6', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.0', 'Programming Language :: Python :: 3.1', 'Programming Language :: Python :: 3.2', 'Programming Language :: Python :: 3.3', 'Topic :: Software Development :: Libraries :: Python Modules', ], )