{"id":20704111,"url":"https://github.com/solidsnack/query-selector","last_synced_at":"2025-04-23T00:48:48.585Z","repository":{"id":53332369,"uuid":"56297572","full_name":"solidsnack/query-selector","owner":"solidsnack","description":"Organize app queries in an annotated SQL file","archived":false,"fork":false,"pushed_at":"2016-05-19T06:55:27.000Z","size":12,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-23T00:48:35.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solidsnack.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-15T06:44:27.000Z","updated_at":"2022-08-04T18:55:12.000Z","dependencies_parsed_at":"2022-09-05T02:21:56.035Z","dependency_job_id":null,"html_url":"https://github.com/solidsnack/query-selector","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidsnack%2Fquery-selector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidsnack%2Fquery-selector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidsnack%2Fquery-selector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidsnack%2Fquery-selector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidsnack","download_url":"https://codeload.github.com/solidsnack/query-selector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250348878,"owners_count":21415910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T01:11:00.743Z","updated_at":"2025-04-23T00:48:48.568Z","avatar_url":"https://github.com/solidsnack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"==================\n``query-selector``\n==================\n\n.. image:: https://travis-ci.org/solidsnack/query-selector.svg?branch=master\n    :target: https://travis-ci.org/solidsnack/query-selector\n\nQuery selector allows one treat a file full of SQL queries as a record, with\none attribute for each annotated query. This makes working with long, ad-hoc\nSQL queries more hygienic, and has the benefit of making it easy to find the\nqueries.\n\nThe ``QuerySelector`` constructor accepts a string, file handle or\n``(\u003cpackage\u003e, \u003cresource)`` pair and parses the SQL into groups annotated with\n``--@ \u003cname\u003e \u003cmode\u003e``. The ``\u003cname\u003e`` is any Python compatible name; it will\nbecome an attribute of the object. The ``\u003cmode\u003e`` is merely metadata, and can\nbe omitted; it describes whether a query should have one, none or many\nresults.\n\nFor example, a file like this:\n\n.. code:: sql\n\n    --@ t one\n    SELECT now();\n\nbecomes an object with a single attribute ``t``:\n\n.. code:: pycon\n\n    \u003e\u003e\u003e q.t\n    Query(args=[], mode=u'one', readonly=False, text=u'SELECT * FROM now();')\n\nA ``QuerySelector`` object is iterable, providing pairs of name and query in\nthe order that the queries originally appeared in the file.\n\n.. code:: pycon\n\n    \u003e\u003e\u003e for name, q in qs:\n    ...     print '%s: %s' % (name, q)\n    t: Query(args=[], mode=u'one', readonly=True, text='SELECT now();')\n\n--------------------\nThe Query Convention\n--------------------\n\nIf you have a script `task.py` and a SQL file `task.sql`, or a module in a\npackage `package/module.py` and a SQL file `package/module.sql`, QuerySelector\nhas a shortcut for you:\n\n.. code:: python\n\n    from query_selector.magic import queries\n\n\n    for q in queries:\n        print q\n\nThe ``magic`` module overrides the normal module loading machinery to\ndetermine which script or module is importing it and locate an adjacent SQL\nfile. This magic is in a separate module to make it stricly opt-in!\n\n-----\nModes\n-----\n\nModes can be one of ``none``, ``one``, ``one?`` and ``many``. When not\nspecified, default is ``many``. A mode string can also be followed with the\nsingle word ``ro`` as a clue that the query is read-only.\n\nRealistically, ``SELECT now()`` is a read-only query. We can annotate it as\nsuch, the resulting query datastructure records this:\n\n.. code:: pycon\n\n    \u003e\u003e\u003e QuerySelector(\"\"\"\n    ...   --@ t one ro\n    ...   SELECT now();\n    ... \"\"\").t\n    Query(args=[], mode=u'one', readonly=True, text=u'SELECT * FROM now();')\n\n----------\nParameters\n----------\n\n``query-selector`` recognizes the ``%(...)s`` style parameter references\ndefined in Python DBI 2.0. Say that we'd like to pass a timezone\nwhen selecting the server time. We can do so by adding ``AT TIME ZONE %(tz)s``\nto our query. The presence of this parameter is stored in the ``args`` field\nof the parsed result. (The parameters in ``.args`` are listed in the order of\ntheir first appearance in the query.)\n\n.. code:: pycon\n\n    \u003e\u003e\u003e QuerySelector(\"\"\"\n    ...     --@ t one ro\n    ...     SELECT now() AT TIME ZONE %(tz)s AS t;\n    ... \"\"\").t\n    Query(args=[u'tz'], mode=u'one', readonly=True,\n          text=u'SELECT now() AT TIME ZONE %(tz)s AS t;')\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidsnack%2Fquery-selector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidsnack%2Fquery-selector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidsnack%2Fquery-selector/lists"}