socialvec 0.1.7__tar.gz → 0.2.0__tar.gz

{socialvec-0.1.7 → socialvec-0.2.0}/AUTHORS.rst

@@ -1,13 +1,13 @@
-=======
-Credits
-=======
-
-Development Lead
-----------------
-
-* Nir Lotan <nir.lotan@gmail.com>
-
-Contributors
-------------
-
-None yet. Why not be the first?
+=======
+Credits
+=======
+
+Development Lead
+----------------
+
+* Nir Lotan <nir.lotan@gmail.com>
+
+Contributors
+------------
+
+None yet. Why not be the first?

{socialvec-0.1.7 → socialvec-0.2.0}/CONTRIBUTING.rst

@@ -1,128 +1,131 @@
-.. highlight:: shell
-
-============
-Contributing
-============
-
-Contributions are welcome, and they are greatly appreciated! Every little bit
-helps, and credit will always be given.
-
-You can contribute in many ways:
-
-Types of Contributions
-----------------------
-
-Report Bugs
-~~~~~~~~~~~
-
-Report bugs at https://github.com/nirlotan/socialvec/issues.
-
-If you are reporting a bug, please include:
-
-* Your operating system name and version.
-* Any details about your local setup that might be helpful in troubleshooting.
-* Detailed steps to reproduce the bug.
-
-Fix Bugs
-~~~~~~~~
-
-Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
-wanted" is open to whoever wants to implement it.
-
-Implement Features
-~~~~~~~~~~~~~~~~~~
-
-Look through the GitHub issues for features. Anything tagged with "enhancement"
-and "help wanted" is open to whoever wants to implement it.
-
-Write Documentation
-~~~~~~~~~~~~~~~~~~~
-
-SocialVec could always use more documentation, whether as part of the
-official SocialVec docs, in docstrings, or even on the web in blog posts,
-articles, and such.
-
-Submit Feedback
-~~~~~~~~~~~~~~~
-
-The best way to send feedback is to file an issue at https://github.com/nirlotan/socialvec/issues.
-
-If you are proposing a feature:
-
-* Explain in detail how it would work.
-* Keep the scope as narrow as possible, to make it easier to implement.
-* Remember that this is a volunteer-driven project, and that contributions
-  are welcome :)
-
-Get Started!
-------------
-
-Ready to contribute? Here's how to set up `socialvec` for local development.
-
-1. Fork the `socialvec` repo on GitHub.
-2. Clone your fork locally::
-
-    $ git clone git@github.com:your_name_here/socialvec.git
-
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
-
-    $ mkvirtualenv socialvec
-    $ cd socialvec/
-    $ python setup.py develop
-
-4. Create a branch for local development::
-
-    $ git checkout -b name-of-your-bugfix-or-feature
-
-   Now you can make your changes locally.
-
-5. When you're done making changes, check that your changes pass flake8 and the
-   tests, including testing other Python versions with tox::
-
-    $ flake8 socialvec tests
-    $ python setup.py test or pytest
-    $ tox
-
-   To get flake8 and tox, just pip install them into your virtualenv.
-
-6. Commit your changes and push your branch to GitHub::
-
-    $ git add .
-    $ git commit -m "Your detailed description of your changes."
-    $ git push origin name-of-your-bugfix-or-feature
-
-7. Submit a pull request through the GitHub website.
-
-Pull Request Guidelines
------------------------
-
-Before you submit a pull request, check that it meets these guidelines:
-
-1. The pull request should include tests.
-2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check
-   https://travis-ci.com/nirlotan/socialvec/pull_requests
-   and make sure that the tests pass for all supported Python versions.
-
-Tips
-----
-
-To run a subset of tests::
-
-
-    $ python -m unittest tests.test_socialvec
-
-Deploying
----------
-
-A reminder for the maintainers on how to deploy.
-Make sure all your changes are committed (including an entry in HISTORY.rst).
-Then run::
-
-$ bump2version patch # possible: major / minor / patch
-$ git push
-$ git push --tags
-
-Travis will then deploy to PyPI if tests pass.
+.. highlight:: shell
+
+============
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+Types of Contributions
+----------------------
+
+Report Bugs
+~~~~~~~~~~~
+
+Report bugs at https://github.com/nirlotan/socialvec/issues.
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug.
+
+Fix Bugs
+~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
+wanted" is open to whoever wants to implement it.
+
+Implement Features
+~~~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+SocialVec could always use more documentation, whether as part of the
+official SocialVec docs, in docstrings, or even on the web in blog posts,
+articles, and such.
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at https://github.com/nirlotan/socialvec/issues.
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+Get Started!
+------------
+
+Ready to contribute? Here's how to set up `socialvec` for local development.
+
+1. Fork the `socialvec` repo on GitHub.
+2. Clone your fork locally::
+
+    $ git clone git@github.com:your_name_here/socialvec.git
+
+3. Install your local copy and the development tools into a virtual environment::
+
+    $ cd socialvec/
+    $ python -m venv .venv
+    $ source .venv/bin/activate      # on Windows: .venv\Scriptsctivate
+    $ pip install -r requirements_dev.txt -e ".[classifier,api]"
+
+4. Create a branch for local development::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass flake8 and the
+   tests, including testing other Python versions with tox::
+
+    $ flake8 socialvec tests
+    $ pytest
+    $ tox
+
+   The first test run downloads the models (about 150 MB each) into
+   ``~/.cache/socialvec``; set ``SOCIALVEC_HOME`` to use another folder.
+
+6. Commit your changes and push your branch to GitHub::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+7. Submit a pull request through the GitHub website.
+
+Pull Request Guidelines
+-----------------------
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to README.md.
+3. The pull request should work for Python 3.10 to 3.13. The GitHub Actions
+   tests run on every pull request; make sure they pass.
+
+Tips
+----
+
+To run a subset of tests::
+
+    $ pytest tests/test_cli.py
+
+Deploying
+---------
+
+A reminder for the maintainers on how to deploy.
+Make sure all your changes are committed (including an entry in HISTORY.rst).
+Then run::
+
+$ bump2version patch # possible: major / minor / patch
+$ git push
+$ git push --tags
+
+Then create a GitHub release for the new tag. The ``Publish`` GitHub Actions
+workflow builds the package and uploads it to PyPI (using PyPI trusted
+publishing, so no token is stored anywhere). To upload by hand instead, run
+``make release``.

socialvec-0.2.0/HISTORY.rst

@@ -0,0 +1,95 @@
+History
+-------
+
+0.1.0 (2022-09-29)
+------------------
+
+* First release on PyPI.
+
+0.1.1 (2022-09-29)
+------------------
+
+* Include config.yaml in the distribution.
+
+0.1.2 (2022-10-02)
+------------------
+
+* Rearrange config.yaml
+* Support multiple versions of the SocialVec model
+* Fix bug when searching for similarity using username
+
+0.1.3 (2022-10-14)
+------------------
+* Initial version of SocialVecClassifier
+
+0.1.4 (2022-11-08)
+------------------
+* Updates to SocialVecClassifier
+
+0.1.5 (2023-11-07)
+------------------
+* Update a dedicated model for the SocialVecClassifier (2020c)
+
+0.1.6 (2023-11-09)
+------------------
+* Modify requirements to support more up-to-date python versions
+
+0.1.7 (2024-10-22)
+------------------
+* Add the option to load the model to RAM in case there is no write permission to the package folder.
+
+0.1.7.1 (2024-10-22)
+--------------------
+* Add pypi documentation
+
+0.2.0 (2026-11-07)
+------------------
+
+Highlights: many lookup bugs fixed, safer and cached downloads, optional TensorFlow
+and Flask, a hardened HTTP API, and a real command line.
+
+Breaking changes:
+
+* Downloaded models and metadata are now kept in ``~/.cache/socialvec`` (see below). Files
+  saved by older versions are still found, so nothing is downloaded again.
+* TensorFlow is no longer installed by default; install ``socialvec[classifier]`` for the
+  classifiers. Flask is in ``socialvec[api]``.
+* Errors are specific exception classes (all subclasses of ``SocialVecError``) instead of a
+  bare ``Exception``.
+* ``validate_username`` and ``sv[name]`` raise ``UserNotFoundError`` for accounts that are
+  only in the metadata, not in the loaded model.
+* ``socialvec.api`` no longer loads a model when imported (use ``create_app()``), and
+  listens on ``127.0.0.1`` by default.
+* Python 3.8 and 3.9 are no longer supported (both have reached end of life); 3.10 to 3.13 are.
+
+All changes:
+
+* New ``socialvec`` command line: ``similar``, ``similarity``, ``predict`` and ``download``.
+* The README is now the PyPI project description, with up-to-date examples and a citation.
+* User IDs given as numpy integers (e.g. ``np.int64``) now work everywhere; ``get_average_embeddings`` no longer silently drops them.
+* Errors are now ``socialvec.exceptions.InvalidUserIdError`` (a ``ValueError``) and ``UserNotFoundError`` (a ``KeyError``), both subclasses of ``SocialVecError``, instead of a bare ``Exception``.
+* Looking up a username that is in the metadata but not in the loaded model raises ``UserNotFoundError`` instead of gensim's ``KeyError``.
+* When several accounts share a screen name, the one that is in the loaded model is used.
+* Username lookups are now a dictionary lookup instead of a scan of the whole metadata table.
+* ``get_screen_name`` returns ``None`` for users that are in the model but have no metadata, instead of raising ``IndexError``.
+* ``get_similar`` accepts a list of usernames as well as user IDs.
+* ``init_classifier()`` raises a clear error for models with no classifiers (classifiers are only available for ``2020c``), and ``predict`` raises one for unknown classifier names.
+* Fix ``f1_m`` (it referred to ``self`` from a static method).
+* Remove the hard-coded vector size of 100.
+* API (``socialvec.api``):
+
+  * The model is chosen with ``SOCIALVEC_MODEL`` (default ``2020``). ``/predict`` and ``/predict_proba`` need ``2020c``, and return 501 with an explanation on other models instead of failing on every request.
+  * Classifiers are loaded once when the app is created, not lazily on the first request.
+  * App setup moved into ``create_app()``; importing the module no longer downloads or loads a model. ``python -m socialvec.api`` still works.
+  * Listens on ``127.0.0.1`` by default instead of ``0.0.0.0``; set ``SOCIALVEC_HOST`` and ``PORT`` to change it. Allowed CORS origins come from ``SOCIALVEC_CORS_ORIGINS`` (default ``*``).
+  * Errors: 400 for invalid input (including a non-integer ``topn`` and missing or non-JSON bodies), 404 for users not in the model, and a generic 500 for unexpected errors, which are logged instead of returned to the client.
+  * ``/get_similar`` clamps ``topn`` to 1-100 and returns ``application/json``.
+* Downloaded models and metadata are now kept in ``~/.cache/socialvec`` (or the folder in the ``SOCIALVEC_HOME`` environment variable) instead of the package folder. Files that older versions saved in the package folder or the working folder are still used, so they are not downloaded again.
+* Downloads are checked against a SHA-256 checksum before they are loaded.
+* A failed download now raises ``SocialVecError`` instead of leaving a broken ``SocialVec`` object that fails later with ``AttributeError``.
+* Fix loading the wrong model (always ``2020_2022``) when the package folder was not writable.
+* The metadata is downloaded once and cached, instead of being read from Dropbox every time when the package folder was not writable.
+* An unknown ``model_name`` raises ``UnknownModelError`` (a ``ValueError``) listing the available models.
+* TensorFlow is now an optional extra: ``pip install "socialvec[classifier]"``. The embeddings work without it; ``init_classifier()`` raises a clear error if it is missing. Flask is an optional extra too: ``pip install "socialvec[api]"``.
+* ``wget`` is no longer a dependency; downloads use ``requests``.
+* Packaging: ship ``config.yaml`` and the classifier ``.h5`` files in the package, and never the downloaded models.

{socialvec-0.1.7 → socialvec-0.2.0}/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2022, Nir Lotan
-
-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.
-
+MIT License
+
+Copyright (c) 2022, Nir Lotan
+
+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.
+

{socialvec-0.1.7 → socialvec-0.2.0}/MANIFEST.in

@@ -1,16 +1,13 @@
-include AUTHORS.rst
-include CONTRIBUTING.rst
-include HISTORY.rst
-include LICENSE
-include README.rst
-
-recursive-include socialvec *
-recursive-include tests *
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-recursive-exclude *.gz
-exclude socialvec/SocialVec2020_2022.pkl.gz
-exclude socialvec/SocialVec2020.pkl.gz
-exclude socialvec/metadata.parquet.gz
-
-recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
+include AUTHORS.rst
+include CONTRIBUTING.rst
+include HISTORY.rst
+include LICENSE
+include README.md
+
+recursive-include socialvec *
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+global-exclude *.pkl.gz metadata.parquet.gz *.part .DS_Store
+
+recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif