| Name | imessage-conversation-analyzer JSON |
| Version |
2.3.0
JSON |
| download |
| home_page | |
| Summary | Analyzes the entire history of a macOS Messages conversation |
| upload_time | 2024-03-06 23:09:33 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | The MIT License (MIT) Copyright (c) 2020-2024 Caleb Evans 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. |
| keywords |
apple
imessage
macos
conversation
chat
analysis
pandas
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# iMessage Conversation Analyzer
*Copyright 2020-2024 Caleb Evans*
*Released under the MIT license*
[](https://github.com/caleb531/imessage-conversation-analyzer/actions/workflows/tests.yml)
[](https://coveralls.io/r/caleb531/imessage-conversation-analyzer?branch=main)
iMessage Conversation Analyzer (ICA) is a fully-typed Python library that will
read the contents of an iMessage conversation via the Messages app's database on
macOS. You can then gather various metrics of interest on the messages. The library also includes a CLI utility for easy use.
Much of this program was inspired by and built using findings from [this blog post by Yorgos Askalidis][blog-post].
[blog-post]: https://towardsdatascience.com/heres-how-you-can-access-your-entire-imessage-history-on-your-mac-f8878276c6e9
### Caveats
Please note that currently, you can only query conversations between you and a
single other person (i.e. group chats are currently unsupported).
It should also be clarified that this program only supports macOS, since the
presence of the chat.db file in your user Library directory is essential for the
program to function.
## Installation
### 1. Install Python 3
To install Python 3, you'll need to install the Apple Command Line Tools, which
you can install by running:
```sh
xcode-select --install
```
Don't worry if you see a long download time; it will shorten rather quickly.
### 2. Set up virtualenv
```sh
pip3 install virtualenv
```
```sh
virtualenv --python=python3 .virtualenv
source .virtualenv/bin/activate
```
### 3. Install project depdendencies
```sh
pip install -r requirements.txt
```
## Usage
The package includes both a Command Line API for simplicity/convenience, as well
as a Python API for maximum flexibility.
### Command Line API
To use ICA from the command line, simply invoke the `ica` command. The minimum required arguments are:
1. A path to an analyzer file to run, or the name of a built-in analyzer
2. The first and last name of the contact, via the `-c`/`--contact` flag
1. If the contact has no last name on record, you can just pass the first
name
### Other formats
You can optionally pass the `-f`/`--format` flag to output to a specific format
like CSV (supported formats include `csv`, `excel`/`xlsx`, and `markdown`/`md`).
```sh
ica message_totals -c 'Jane Fernbrook' -f csv
```
```sh
ica ./my_custom_analyzer.py -c 'Jane Fernbrook' -f csv
```
### Writing to a file
Finally, there is an optional `-o`/`--output` flag if you want to output to a
specified file. ICA will do its best to infer the format from the file
extension, although you could also pass `--format` if you have special filename
requirements.
```sh
ica transcript -c 'Thomas Riverstone' -o ./my_transcript.xlsx
```
#### Built-in analyzers
The library includes several built-in analyzers so that you can use ICA out of
the box:
1. `message_totals`: a summary of message and reaction counts, by person and in
total, as well as other insightful metrics
2. `attachment_totals`: lists count data by attachment type, including
number of Spotify links shared, YouTube videos, Apple Music, etc.
3. `most_frequent_emojis`: count data for the top 10 most frequently used emojis
across the entire conversation
4. `totals_by_day`: a comprehensive breakdown of message totals for every day
you and the other person have been messaging in the conversation
5. `transcript`: a full, unedited transcript of every message, including
reactions, between you and the other person (attachment files not included)
Again, to call one of these built-in analyzers, just pass it as the first
argument to the `ica` command:
```sh
ica most_frequent_emojis -c 'Jane Fernbrook'
```
### Python API
The Python API is much more powerful, allowing you to integrate ICA into any
type of Python project that can run on macOS. All of the built-in analyzers
themselves (under the `ica/analyzers` directory) actually use this API.
```python
# get_my_transcript.py
import pandas as pd
import ica
# Export a transcript of the entire conversation
def main() -> None:
# Allow your program to accept all the same CLI arguments as the `ica`
# command; you can skip calling this if have other means of specifying the
# contact name and output format
cli_args = ica.get_cli_args()
# Retrieve the dataframes corresponding to the massaged contents of the
# database; dataframes include `message` and `attachment`
dfs = ica.get_dataframes(
contact_name=cli_args.contact_name,
timezone=cli_args.timezone
)
# Send the results to stdout (or to file) in the given format
ica.output_results(
pd.DataFrame(
{
"timestamp": dfs.messages["datetime"],
"is_from_me": dfs.messages["is_from_me"],
"is_reaction": dfs.messages["is_reaction"],
# U+FFFC is the object replacement character, which appears as
# the textual message for every attachment
"message": dfs.messages["text"].replace(
r"\ufffc", "(attachment)", regex=True
),
}
),
# The default format (None) corresponds to the pandas default dataframe
# table format
format=cli_args.format,
# When output is None (the default), ICA will print to stdout
output=cli_args.output,
)
if __name__ == "__main__":
main()
```
You can run the above program using the `ica` command, or execute it directly
like any other Python program.
```sh
ica ./get_my_transcript.py -c 'Thomas Riverstone'
```
```sh
python ./get_my_transcript.py -c 'Thomas Riverstone'
```
```sh
python -m get_my_transcript -c 'Thomas Riverstone'
```
You're not limited to writing a command line program, though! The
`ica.get_dataframes()` function is the only function you will need in any
analyzer program. But beyond that, feel free to import other modules, send your
results to other processes, or whatever you need to do!
You can also import any built-in analyzer (for your own post-processing) via the
`ica.analyzers` namespace.
### Errors and exceptions
- `BaseAnalyzerException`: the base exception class for all library-related
errors and exceptions
- `ContactNotFoundError`: raised if the specified contact was not found
- `ConversationNotFoundError`: raised if the specified conversation was not
found
- `FormatNotSupportedError`: raised if the specified format is not supported by
the library
#### Using a specific timezone
By default, all dates and times are in the local timezone of the system on which
ICA is run. If you'd like to change this, you can pass the `--timezone` / `-t`
option to the CLI with an IANA timezone name.
```sh
ica totals_by_day -c 'Daniel Brightingale' -t UTC
```
```sh
ica totals_by_day -c 'Daniel Brightingale' -t America/New_York
```
The equivalent option for the Python API is the `timezone` parameter to
`ica.get_dataframes`:
```python
dfs = ica.get_dataframes(contact_name=my_contact_name, timezone='UTC')
```
Raw data
{
"_id": null,
"home_page": "",
"name": "imessage-conversation-analyzer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Caleb Evans <caleb@calebevans.me>",
"keywords": "apple,imessage,macos,conversation,chat,analysis,pandas",
"author": "",
"author_email": "Caleb Evans <caleb@calebevans.me>",
"download_url": "https://files.pythonhosted.org/packages/a9/bd/6835271a9789b626bc83a3b72cd37eb7e499c9ac9d3d5f3eecd8d7e356b9/imessage-conversation-analyzer-2.3.0.tar.gz",
"platform": null,
"description": "# iMessage Conversation Analyzer\n\n*Copyright 2020-2024 Caleb Evans* \n*Released under the MIT license*\n\n[](https://github.com/caleb531/imessage-conversation-analyzer/actions/workflows/tests.yml)\n[](https://coveralls.io/r/caleb531/imessage-conversation-analyzer?branch=main)\n\niMessage Conversation Analyzer (ICA) is a fully-typed Python library that will\nread the contents of an iMessage conversation via the Messages app's database on\nmacOS. You can then gather various metrics of interest on the messages. The library also includes a CLI utility for easy use.\n\nMuch of this program was inspired by and built using findings from [this blog post by Yorgos Askalidis][blog-post].\n\n[blog-post]: https://towardsdatascience.com/heres-how-you-can-access-your-entire-imessage-history-on-your-mac-f8878276c6e9\n\n### Caveats\n\nPlease note that currently, you can only query conversations between you and a\nsingle other person (i.e. group chats are currently unsupported).\n\nIt should also be clarified that this program only supports macOS, since the\npresence of the chat.db file in your user Library directory is essential for the\nprogram to function.\n\n## Installation\n\n### 1. Install Python 3\n\nTo install Python 3, you'll need to install the Apple Command Line Tools, which\nyou can install by running:\n\n```sh\nxcode-select --install\n```\n\nDon't worry if you see a long download time; it will shorten rather quickly.\n\n### 2. Set up virtualenv\n\n```sh\npip3 install virtualenv\n```\n\n```sh\nvirtualenv --python=python3 .virtualenv\nsource .virtualenv/bin/activate\n```\n\n### 3. Install project depdendencies\n\n```sh\npip install -r requirements.txt\n```\n\n## Usage\n\nThe package includes both a Command Line API for simplicity/convenience, as well\nas a Python API for maximum flexibility.\n\n### Command Line API\n\nTo use ICA from the command line, simply invoke the `ica` command. The minimum required arguments are:\n\n1. A path to an analyzer file to run, or the name of a built-in analyzer\n2. The first and last name of the contact, via the `-c`/`--contact` flag\n 1. If the contact has no last name on record, you can just pass the first\n name\n\n### Other formats\n\nYou can optionally pass the `-f`/`--format` flag to output to a specific format\nlike CSV (supported formats include `csv`, `excel`/`xlsx`, and `markdown`/`md`).\n\n```sh\nica message_totals -c 'Jane Fernbrook' -f csv\n```\n\n```sh\nica ./my_custom_analyzer.py -c 'Jane Fernbrook' -f csv\n```\n\n### Writing to a file\n\nFinally, there is an optional `-o`/`--output` flag if you want to output to a\nspecified file. ICA will do its best to infer the format from the file\nextension, although you could also pass `--format` if you have special filename\nrequirements.\n\n```sh\nica transcript -c 'Thomas Riverstone' -o ./my_transcript.xlsx\n```\n\n#### Built-in analyzers\n\nThe library includes several built-in analyzers so that you can use ICA out of\nthe box:\n\n1. `message_totals`: a summary of message and reaction counts, by person and in\n total, as well as other insightful metrics\n2. `attachment_totals`: lists count data by attachment type, including\n number of Spotify links shared, YouTube videos, Apple Music, etc.\n3. `most_frequent_emojis`: count data for the top 10 most frequently used emojis\n across the entire conversation\n4. `totals_by_day`: a comprehensive breakdown of message totals for every day\n you and the other person have been messaging in the conversation\n5. `transcript`: a full, unedited transcript of every message, including\n reactions, between you and the other person (attachment files not included)\n\nAgain, to call one of these built-in analyzers, just pass it as the first\nargument to the `ica` command:\n\n```sh\nica most_frequent_emojis -c 'Jane Fernbrook'\n```\n\n### Python API\n\nThe Python API is much more powerful, allowing you to integrate ICA into any\ntype of Python project that can run on macOS. All of the built-in analyzers\nthemselves (under the `ica/analyzers` directory) actually use this API.\n\n```python\n# get_my_transcript.py\n\nimport pandas as pd\n\nimport ica\n\n\n# Export a transcript of the entire conversation\ndef main() -> None:\n # Allow your program to accept all the same CLI arguments as the `ica`\n # command; you can skip calling this if have other means of specifying the\n # contact name and output format\n cli_args = ica.get_cli_args()\n # Retrieve the dataframes corresponding to the massaged contents of the\n # database; dataframes include `message` and `attachment`\n dfs = ica.get_dataframes(\n contact_name=cli_args.contact_name,\n timezone=cli_args.timezone\n )\n # Send the results to stdout (or to file) in the given format\n ica.output_results(\n pd.DataFrame(\n {\n \"timestamp\": dfs.messages[\"datetime\"],\n \"is_from_me\": dfs.messages[\"is_from_me\"],\n \"is_reaction\": dfs.messages[\"is_reaction\"],\n # U+FFFC is the object replacement character, which appears as\n # the textual message for every attachment\n \"message\": dfs.messages[\"text\"].replace(\n r\"\\ufffc\", \"(attachment)\", regex=True\n ),\n }\n ),\n # The default format (None) corresponds to the pandas default dataframe\n # table format\n format=cli_args.format,\n # When output is None (the default), ICA will print to stdout\n output=cli_args.output,\n )\n\n\nif __name__ == \"__main__\":\n main()\n```\n\nYou can run the above program using the `ica` command, or execute it directly\nlike any other Python program.\n\n```sh\nica ./get_my_transcript.py -c 'Thomas Riverstone'\n```\n\n```sh\npython ./get_my_transcript.py -c 'Thomas Riverstone'\n```\n\n```sh\npython -m get_my_transcript -c 'Thomas Riverstone'\n```\n\nYou're not limited to writing a command line program, though! The\n`ica.get_dataframes()` function is the only function you will need in any\nanalyzer program. But beyond that, feel free to import other modules, send your\nresults to other processes, or whatever you need to do!\n\nYou can also import any built-in analyzer (for your own post-processing) via the\n`ica.analyzers` namespace.\n\n### Errors and exceptions\n\n- `BaseAnalyzerException`: the base exception class for all library-related\n errors and exceptions\n- `ContactNotFoundError`: raised if the specified contact was not found\n- `ConversationNotFoundError`: raised if the specified conversation was not\n found\n- `FormatNotSupportedError`: raised if the specified format is not supported by\n the library\n\n#### Using a specific timezone\n\nBy default, all dates and times are in the local timezone of the system on which\nICA is run. If you'd like to change this, you can pass the `--timezone` / `-t`\noption to the CLI with an IANA timezone name.\n\n```sh\nica totals_by_day -c 'Daniel Brightingale' -t UTC\n```\n\n```sh\nica totals_by_day -c 'Daniel Brightingale' -t America/New_York\n```\n\nThe equivalent option for the Python API is the `timezone` parameter to\n`ica.get_dataframes`:\n\n```python\ndfs = ica.get_dataframes(contact_name=my_contact_name, timezone='UTC')\n```\n",
"bugtrack_url": null,
"license": "The MIT License (MIT) Copyright (c) 2020-2024 Caleb Evans 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. ",
"summary": "Analyzes the entire history of a macOS Messages conversation",
"version": "2.3.0",
"project_urls": {
"changelog": "https://github.com/caleb531/imessage-conversation-analyzer/releases",
"documentation": "https://github.com/caleb531/imessage-conversation-analyzer#readme",
"homepage": "https://github.com/caleb531/imessage-conversation-analyzer",
"repository": "https://github.com/caleb531/imessage-conversation-analyzer"
},
"split_keywords": [
"apple",
"imessage",
"macos",
"conversation",
"chat",
"analysis",
"pandas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a08c6273c5d18869dd13d76b799b8f82950fa962da3931e57685dffb1a4877b4",
"md5": "68d7fee74da0409b6d5df44c59322a49",
"sha256": "294d7e2f4f59b409a58807d91a3c1f9c77a99eec96115132f4abdf441253f923"
},
"downloads": -1,
"filename": "imessage_conversation_analyzer-2.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68d7fee74da0409b6d5df44c59322a49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25862,
"upload_time": "2024-03-06T23:09:28",
"upload_time_iso_8601": "2024-03-06T23:09:28.333213Z",
"url": "https://files.pythonhosted.org/packages/a0/8c/6273c5d18869dd13d76b799b8f82950fa962da3931e57685dffb1a4877b4/imessage_conversation_analyzer-2.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9bd6835271a9789b626bc83a3b72cd37eb7e499c9ac9d3d5f3eecd8d7e356b9",
"md5": "c55abcb842b083f6143f0b0ad3d8c3df",
"sha256": "9441b8d2b78a1c874b9c0e5f7d482e7c0cd48b28f93e1836e22215a8a4b3d255"
},
"downloads": -1,
"filename": "imessage-conversation-analyzer-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "c55abcb842b083f6143f0b0ad3d8c3df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 30047,
"upload_time": "2024-03-06T23:09:33",
"upload_time_iso_8601": "2024-03-06T23:09:33.993566Z",
"url": "https://files.pythonhosted.org/packages/a9/bd/6835271a9789b626bc83a3b72cd37eb7e499c9ac9d3d5f3eecd8d7e356b9/imessage-conversation-analyzer-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 23:09:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caleb531",
"github_project": "imessage-conversation-analyzer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "imessage-conversation-analyzer"
}
