{"id":25927845,"url":"https://github.com/samirelanduk/pychats","last_synced_at":"2026-06-08T15:32:48.159Z","repository":{"id":30137054,"uuid":"33687131","full_name":"samirelanduk/pychats","owner":"samirelanduk","description":"Python project for messages extraction and analytics","archived":false,"fork":false,"pushed_at":"2017-08-29T19:22:00.000Z","size":416,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-05T20:46:03.351Z","etag":null,"topics":["conversations","facebook","facebook-messenger","messaging","python"],"latest_commit_sha":null,"homepage":"https://pychats.samireland.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samirelanduk.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-09T19:05:04.000Z","updated_at":"2022-01-06T03:15:22.000Z","dependencies_parsed_at":"2022-08-17T18:35:11.004Z","dependency_job_id":null,"html_url":"https://github.com/samirelanduk/pychats","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/samirelanduk/pychats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samirelanduk%2Fpychats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samirelanduk%2Fpychats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samirelanduk%2Fpychats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samirelanduk%2Fpychats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samirelanduk","download_url":"https://codeload.github.com/samirelanduk/pychats/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samirelanduk%2Fpychats/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34069490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["conversations","facebook","facebook-messenger","messaging","python"],"created_at":"2025-03-03T21:10:52.674Z","updated_at":"2026-06-08T15:32:48.139Z","avatar_url":"https://github.com/samirelanduk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"pychats\n=======\n\npychats is a library for modelling text conversations and extracting them from\nexternal sources, like Facebook.\n\nExample\n-------\n\n  \u003e\u003e\u003e import pychats\n  \u003e\u003e\u003e from datetime import datetime\n  \u003e\u003e\u003e conversation = pychats.Conversation()\n  \u003e\u003e\u003e bob = pychats.Contact(\"Bob Loblaw\")\n  \u003e\u003e\u003e message = pychats.Message(\"Hello!\", datetime(1990, 9, 28, 15, 30), bob)\n  conversation.add_message(message)\n  \u003e\u003e\u003e conversation.participants()\n  {\u003cContact: Bob Loblaw\u003e}\n\n\n\n\nInstalling\n----------\n\npip\n~~~\n\npychats can be installed using pip:\n\n``$ pip3 install pychats``\n\npychats is written for Python 3, and does not support Python 2.\n\nIf you get permission errors, try using ``sudo``:\n\n``$ sudo pip3 install pychats``\n\n\nDevelopment\n~~~~~~~~~~~\n\nThe repository for pychats, containing the most recent iteration, can be\nfound `here \u003chttp://github.com/samirelanduk/pychats/\u003e`_. To clone the\npychats repository directly from there, use:\n\n``$ git clone git://github.com/samirelanduk/pychats.git``\n\n\nRequirements\n~~~~~~~~~~~~\n\npychats requires the\n`BeautifulSoup \u003chttps://www.crummy.com/software/BeautifulSoup/\u003e`_ library, for\nparsing Facebook message files. pip will install this automatically when it\ninstalls pychats.\n\n\nOverview\n--------\n\nCreating ChatLogs manually\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe most direct way to create pychats logs is to create the objects manually.\nUltimately modules will be added to create them by parsing external data\nsources, such as Facebook message logs or iPhone backups, but for now this\nminimal interface works nicely.\n\nPeople\n######\n\nThe first step is to create the contacts who have messages in the chatlog. This\nis done with the ``Contact`` class:\n\n  \u003e\u003e\u003e import pychats\n  \u003e\u003e\u003e harry = pychats.Contact(\"Harry Potter\")\n  \u003e\u003e\u003e ronald = pychats.Contact(\"Ron Weasley\")\n  \u003e\u003e\u003e hermione = pychats.Contact(\"Hermione Granger\")\n  \u003e\u003e\u003e harry.name()\n  'Harry Potter'\n  \u003e\u003e\u003e ronald.name()\n  'Ron Weasley'\n  \u003e\u003e\u003e hermione.name()\n  'Hermione Granger'\n\nYou can give these people 'tags' to categorise them:\n\n  \u003e\u003e\u003e harry.add_tag(\"wizard\")\n  \u003e\u003e\u003e harry.add_tag(\"gryffindor\")\n  \u003e\u003e\u003e harry.tags()\n  {'wizard', 'gryffindor'}\n\n\nConversations and Messages\n##########################\n\nA chatlog is just a collection of conversations, which are themselves just a\nseries of messages. You create conversations with the ``Conversation``\nclass:\n\n\u003e\u003e\u003e harry_conv = pychats.Conversation()\n\u003e\u003e\u003e ron_conv = pychats.Conversation()\n\u003e\u003e\u003e harry_conv\n\u003cConversation (0 messages)\u003e\n\u003e\u003e\u003e ron_conv\n\u003cConversation (0 messages)\u003e\n\nYou do need to pass any arguments when you create the conversation.\n\nThese are not much use without messages. These are created with the\n``Message`` class, and need text, a timestamp, and a sender:\n\n  \u003e\u003e\u003e from datetime import datetime\n  \u003e\u003e\u003e message1 = pychats.Message(\"Hi Harry\", datetime(1993, 1, 5, 8, 2), hermione)\n  \u003e\u003e\u003e message2 = pychats.Message(\"Hi!\", datetime(1993, 1, 5, 8, 7), harry)\n  \u003e\u003e\u003e harry_conv.add_message(message1)\n  \u003e\u003e\u003e harry_conv.add_message(message2)\n  \u003e\u003e\u003e harry_conv\n  \u003cConversation (2 messages)\u003e\n  \u003e\u003e\u003e harry_conv.messages()\n  [\u003cMessage from Hermione Granger at 1993-01-05 08:02\u003e, \u003cMessage from Harry Pott\n  er at 1993-01-05 08:07\u003e]\n  \u003e\u003e\u003e harry_conv.participants()\n  {\u003cContact: Hermione Granger\u003e, \u003cContact: Harry Potter\u003e}\n\nIt doesn't matter what order you add messages in, they will always be ordered by\ntheir timestamp.\n\nChatLogs\n########\n\nChatLogs are created with the ``ChatLog`` class:\n\n  \u003e\u003e\u003e log = pychats.ChatLog(\"Hogwarts Data Breach\")\n  \u003e\u003e\u003e log\n  \u003c'Hogwarts Data Breach' ChatLog (0 Conversations)\u003e\n  \u003e\u003e\u003e log.add_conversation(harry_conv)\n  \u003e\u003e\u003e log\n  \u003c'Hogwarts Data Breach' ChatLog (1 Conversation)\u003e\n\nOnce added, conversations will know what chatlog they are in:\n\n  \u003e\u003e\u003e harry_conv.chatlog()\n  \u003c'Hogwarts Data Breach' ChatLog (1 Conversation)\u003e\n\n\nChatLogs from Facebook\n~~~~~~~~~~~~~~~~~~~~~~\n\nA far more useful feature of pychats, is the ability to create a ChatLog from a\nuser's actual Facebook message history.\n\nTo do this you will first need to download a backup of your Facebook account. If\nyou are logged in, Facebook lets you do this from the\n`Facebook settings page \u003chttps://www.facebook.com/settings\u003e`_.\n\nOnce downloaded, you will need to extract the .zip file you get, and find a file\ncalled messages.htm - this is a document containing all your Facebook messages.\n\n.. WARNING::\n   This is your Facebook message history. *All* of it. These messages are\n   private information - a lot of it concentrated in a single file - and\n   presumably you don't want anyone else to see this\n   file. Take great care of the messages.htm file, and consider deleting it\n   when you have got the information from it that you need. And consider if you\n   *really* need a JSON copy of it.\n\n   Also bear in mind that a log of a conversation between you and someone else\n   is owned by them as much as you. Do not share a conversation without their\n   consent.\n\nOnce this file is found, you create a ChatLog from it with one line:\n\n  \u003e\u003e\u003e facebook_log = pychats.from_facebook(\"path/to/messages.htm\")\n\nYou likely have a lot of messages, and this can take many seconds, maybe even a\nminute if it is very large. pychats *is* parsing and extracting data from a very\nlarge .html file after all.\n\nOnce done however, the log works just like the ChatLogs described above. You can\nsave it to JSON (see below) or do whatever you want with it.\n\n\nStoring ChatLogs as JSON\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nChatLogs have a ``ChatLog.save`` method which will save the while\nstructure to file as JSON. You can call ``from_json`` to recreate\nthe structure.\n\n  \u003e\u003e\u003e log.save(\"backup.json\")\n  \u003e\u003e\u003e recovered_log = pychats.from_json(\"backup.json\")\n\nContacts, Messages, Conversations and ChatLogs all have ``to_json`` methods and\n``from_json`` alternative constructors to individually convert them to and from\nJSON if needed.\n\n  \u003e\u003e\u003e message1.to_json()\n  {'text': 'Hi!', 'timestamp': '1993-01-05 08:07:00', 'sender': {'name': 'Harry\n  Potter', 'tags': []}}\n\n\nChangelog\n---------\n\n\nRelease 2.2.0\n~~~~~~~~~~~~~\n\n`22 August 2017`\n\n* Added parsing of Facebook message.htm files.\n\n\nRelease 2.1.0\n~~~~~~~~~~~~~\n\n`23 July 2017`\n\n* Added JSON input and output.\n* Gave Contact objects tags.\n\n\nRelease 2.0.0\n~~~~~~~~~~~~~\n\n`9 May 2017`\n\n* Added the basic conversation classes for manual creation of chatlogs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamirelanduk%2Fpychats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamirelanduk%2Fpychats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamirelanduk%2Fpychats/lists"}