{"id":17658830,"url":"https://github.com/volfpeter/mastodon-social-graph","last_synced_at":"2025-07-03T22:33:55.376Z","repository":{"id":138825518,"uuid":"586921371","full_name":"volfpeter/mastodon-social-graph","owner":"volfpeter","description":"Mastodon social graph with an SQL backend, in-memory cache, and built-in, on-demand web scraper.","archived":false,"fork":false,"pushed_at":"2023-01-22T10:03:59.000Z","size":23,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T12:07:04.204Z","etag":null,"topics":["graph","mastodon","mastodon-social-network","python","social-network"],"latest_commit_sha":null,"homepage":"","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/volfpeter.png","metadata":{"files":{"readme":"README.md","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,"governance":null}},"created_at":"2023-01-09T14:46:54.000Z","updated_at":"2025-05-13T12:44:51.000Z","dependencies_parsed_at":"2023-10-02T18:25:26.732Z","dependency_job_id":null,"html_url":"https://github.com/volfpeter/mastodon-social-graph","commit_stats":{"total_commits":3,"total_committers":1,"mean_commits":3.0,"dds":0.0,"last_synced_commit":"f38c423464ae607dc3b2ce8a018e9a5473231a95"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/volfpeter/mastodon-social-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volfpeter%2Fmastodon-social-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volfpeter%2Fmastodon-social-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volfpeter%2Fmastodon-social-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volfpeter%2Fmastodon-social-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volfpeter","download_url":"https://codeload.github.com/volfpeter/mastodon-social-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volfpeter%2Fmastodon-social-graph/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261110586,"owners_count":23111061,"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":["graph","mastodon","mastodon-social-network","python","social-network"],"created_at":"2024-10-23T15:43:25.200Z","updated_at":"2025-07-03T22:33:55.328Z","avatar_url":"https://github.com/volfpeter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mastodon-social-graph\n\nMastodon social graph with an SQL backend, in-memory cache, and built-in, on-demand web scraper.\n\n## Installation\n\nYou can install the library and all its dependencies using `pip install mastodon-social-graph`.\n\n## Getting started\n\n### 1) Register your application to get an access token\n\nLog in to the Mastodon instance you would like the graph to work with and register a new application in the Preferences / Development menu.\n\nAlternatively, you can use `Mastodon.py` to create an application. You can start [here](https://mastodonpy.readthedocs.io/en/stable/).\n\n### 2) Create a Mastodon (`Mastodon.py`) instance\n\nYou can create a `Mastodon` instance like this:\n\n```Python\nfrom mastodon import Mastodon\n\nmastodon_app = Mastodon(\n    access_token=\"\u003cyour-application's-acces-token\u003e\",\n    api_base_url=\"\u003cmastodon-server-url\u003e\",  # E.g. https://mastodon.social\n    ratelimit_method=\"wait\",  # Wait when you hit the rate limit.\n)\n```\n\nFor other options, see `Mastodon.py`'s [documentation](https://mastodonpy.readthedocs.io/en/stable/).\n\n### 3) Create the graph\n\nIf you already have `mastodon_app` -- created in the previous step -- in scope, you can create the graph like this:\n\n```Python\nfrom mastodon_social_graph import MastodonSocialGraph\n\ngraph = MastodonSocialGraph(mastodon_app)\n```\n\n### 4) Load a node and its neighbors\n\nOnce you have the `graph`, you can load the first node from Mastodon like this:\n\n```Python\naccount_name: str = \"mastodon\"\n\nmastodon_account_node = graph.get_node_for_account_name(account_name)\nif mastodon_account_node is None:\n    raise ValueError(\"Node not found.\")\n\n# This call fetches neighbor nodes in the background if they are not stored already locally.\n# If the neighbors of the node are already in the database, no request will be sent to Mastodon.\nneighbors = mastodon_account_node.neighbors\nfor node in neighbors:\n    # `node.external_id` is the account handle, `node.name` is the Mastodon database ID (for technical reasons).\n    print(f\"{node.external_id} ({node.name})\")\n```\n\nFor configuration, utilities, and details, please see the code.\n\n## Related projects\n\nYou can find related projects here:\n\n- [graphscraper](https://github.com/volfpeter/graphscraper)\n- [localclustering](https://github.com/volfpeter/localclustering)\n\n## Notice\n\nUse this library and the fetched data responsibly.\n\nThe Mastodon API is rate limited and paged. Certain methods (e.g. follower loading) of the graph -- and its build-in web scraper -- can result in a large number of requests towards the Mastodon instance. These methods can be quite slow, because by design the web scraper makes only 1 request at a time and it doesn't try to work around the imposed rate limit.\n\n## Dependencies\n\nThe library is built on [graphscraper](https://pypi.org/project/graphscraper/) and [Mastodon.py](https://pypi.org/project/Mastodon.py/), and under the hood `graphscraper` works with an SQL (by default SQLite) database.\n\n## Development\n\nUse `black` for code formatting and `mypy` for static code analysis.\n\n## Contributing\n\nContributions are welcome, but keep in mind this is a hobby project intended for light Mastodon social network analysis and discovery.\n\n## License - MIT\n\nThe library is open-sourced under the conditions of the MIT [license](https://choosealicense.com/licenses/mit/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolfpeter%2Fmastodon-social-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolfpeter%2Fmastodon-social-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolfpeter%2Fmastodon-social-graph/lists"}