Initial version; basic list + member tables, import from MailChimp API

rattail_mailchimp/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Rattail integration with MailChimp
+"""
+
+from ._version import __version__

rattail_mailchimp/_version.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8; -*-
+
+__version__ = '0.1.0'

rattail_mailchimp/commands.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Rattail Commands for MailChimp integration
+"""
+
+from rattail import commands
+from rattail.util import load_object
+
+
+class ImportMailChimp(commands.ImportSubcommand):
+    """
+    Import data to Rattail, from MailChimp API
+    """
+    name = 'import-mailchimp'
+    description = __doc__.strip()
+    default_handler_spec = 'rattail_mailchimp.importing.mailchimp:FromMailChimpToRattail'
+
+    def get_handler_factory(self, **kwargs):
+        if self.config:
+            spec = self.config.get('rattail.importing', 'mailchimp.handler',
+                                   default=self.default_handler_spec)
+        else:
+            # just use default, for sake of cmd line help
+            spec = self.default_handler_spec
+        return load_object(spec)

rattail_mailchimp/db/alembic/versions/805181d09df7_initial_tables.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8; -*-
+"""initial tables
+
+Revision ID: 805181d09df7
+Revises: 8856f697902d
+Create Date: 2021-11-07 21:17:31.196005
+
+"""
+
+from __future__ import unicode_literals, absolute_import
+
+# revision identifiers, used by Alembic.
+revision = '805181d09df7'
+down_revision = None
+branch_labels = ('rattail_mailchimp',)
+depends_on = None
+
+from alembic import op
+import sqlalchemy as sa
+import rattail.db.types
+
+
+
+def upgrade():
+
+    # mailchimp_list
+    op.create_table('mailchimp_list',
+                    sa.Column('uuid', sa.String(length=32), nullable=False),
+                    sa.Column('id', sa.String(length=100), nullable=True),
+                    sa.Column('name', sa.String(length=100), nullable=True),
+                    sa.Column('date_created', sa.DateTime(), nullable=True),
+                    sa.PrimaryKeyConstraint('uuid')
+    )
+
+    # mailchimp_list_member
+    op.create_table('mailchimp_list_member',
+                    sa.Column('uuid', sa.String(length=32), nullable=False),
+                    sa.Column('list_uuid', sa.String(length=32), nullable=False),
+                    sa.Column('id', sa.String(length=32), nullable=True),
+                    sa.Column('email_address', sa.String(length=255), nullable=True),
+                    sa.Column('contact_id', sa.String(length=50), nullable=True),
+                    sa.Column('full_name', sa.String(length=100), nullable=True),
+                    sa.Column('email_type', sa.String(length=10), nullable=True),
+                    sa.Column('status', sa.String(length=20), nullable=True),
+                    sa.Column('unsubscribe_reason', sa.Text(), nullable=True),
+                    sa.Column('last_changed', sa.DateTime(), nullable=True),
+                    sa.Column('source', sa.String(length=255), nullable=True),
+                    sa.ForeignKeyConstraint(['list_uuid'], ['mailchimp_list.uuid'], name='mailchimp_list_member_fk_list'),
+                    sa.PrimaryKeyConstraint('uuid')
+    )
+
+
+def downgrade():
+
+    # mailchimp_list*
+    op.drop_table('mailchimp_list_member')
+    op.drop_table('mailchimp_list')

rattail_mailchimp/db/model.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Database schema extensions for Mailchimp integration
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import orm
+
+from rattail.db import model
+
+
+class MailChimpList(model.Base):
+    """
+    List record cache for MailChimp.
+    """
+    __tablename__ = 'mailchimp_list'
+    model_title = "MailChimp List"
+
+    uuid = model.uuid_column()
+
+    id = sa.Column(sa.String(length=100), nullable=True)
+
+    name = sa.Column(sa.String(length=100), nullable=True)
+
+    date_created = sa.Column(sa.DateTime(), nullable=True)
+
+    def __str__(self):
+        return self.name or ""
+
+
+class MailChimpListMember(model.Base):
+    """
+    ListMember record cache for MailChimp.
+    """
+    __tablename__ = 'mailchimp_list_member'
+    __table_args__ = (
+        sa.ForeignKeyConstraint(['list_uuid'], ['mailchimp_list.uuid'], 
+                                name='mailchimp_list_member_fk_list'),
+    )
+
+    uuid = model.uuid_column()
+
+    list_uuid = sa.Column(sa.String(length=32), nullable=False)
+    list = orm.relationship(MailChimpList, backref='members')
+
+    id = sa.Column(sa.String(length=32), nullable=True)
+
+    email_address = sa.Column(sa.String(length=255), nullable=True)
+
+    contact_id = sa.Column(sa.String(length=50), nullable=True)
+
+    full_name = sa.Column(sa.String(length=100), nullable=True)
+
+    email_type = sa.Column(sa.String(length=10), nullable=True)
+
+    status = sa.Column(sa.String(length=20), nullable=True)
+
+    unsubscribe_reason = sa.Column(sa.Text(), nullable=True)
+
+    last_changed = sa.Column(sa.DateTime(), nullable=True)
+
+    source = sa.Column(sa.String(length=255), nullable=True)
+
+    def __str__(self):
+        return self.email_address or ""

rattail_mailchimp/emails.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Email profiles for Rattail / MailChimp integration
+"""
+
+from rattail.emails import ImporterEmail
+
+
+class rattail_import_mailchimp_updates(ImporterEmail):
+    """
+    Sent when a MailChimp -> Rattail import involves data changes.
+    """
+    handler_spec = 'rattail_mailchimp.importing.mailchimp:FromMailChimpToRattail'
+    abstract = False

rattail_mailchimp/importing/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Importing into Rattail
+"""
+
+from . import model

rattail_mailchimp/importing/mailchimp.py

@@ -0,0 +1,141 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+MailChimp -> Rattail "cache" data import
+"""
+
+import datetime
+
+from mailchimp3 import MailChimp
+
+from rattail import importing
+from rattail.util import OrderedDict
+from rattail.time import localtime, make_utc
+from rattail_mailchimp import importing as mailchimp_importing
+
+
+class FromMailChimpToRattail(importing.ToRattailHandler):
+    """
+    Handler for MailChimp -> Rattail cache import
+    """
+    host_title = "MailChimp"
+    
+    def get_importers(self):
+        importers = OrderedDict()
+        importers['MailChimpList'] = MailChimpListImporter
+        importers['MailChimpListMember'] = MailChimpListMemberImporter
+        return importers
+
+
+class FromMailChimp(importing.Importer):
+    """
+    Base class for importers coming from MailChimp
+    """
+
+    def setup(self):
+        super(FromMailChimp, self).setup()
+
+        self.api_key = self.config.require('mailchimp', 'api_key')
+        self.mailchimp = MailChimp(self.api_key)
+
+    def mailchimp_datetime(self, value):
+        dt = datetime.datetime.strptime(value, '%Y-%m-%dT%H:%M:%S%z')
+        dt = localtime(self.config, dt)
+        return dt
+
+
+class MailChimpListImporter(FromMailChimp, mailchimp_importing.model.MailChimpListImporter):
+    """
+    List importer for MailChimp -> Rattail
+    """
+    key = 'id'
+    supported_fields = [
+        'id',
+        'name',
+        'date_created',
+    ]
+
+    def get_host_objects(self):
+        result = self.mailchimp.lists.all(get_all=True)
+        return result['lists']
+
+    def normalize_host_object(self, mclist):
+        date_created = self.mailchimp_datetime(mclist['date_created'])
+        return {
+            'id': mclist['id'],
+            'name': mclist['name'],
+            'date_created': make_utc(date_created),
+        }
+
+
+class MailChimpListMemberImporter(FromMailChimp, mailchimp_importing.model.MailChimpListMemberImporter):
+    """
+    List importer for MailChimp -> Rattail
+    """
+    key = ('list_id', 'contact_id')
+    supported_fields = [
+        'list_id',
+        'id',
+        'email_address',
+        'contact_id',
+        'full_name',
+        'email_type',
+        'status',
+        # 'unsubscribe_reason',
+        'last_changed',
+        'source',
+    ]
+
+    def get_host_objects(self):
+        model = self.model
+        objects = []
+        mclists = self.session.query(model.MailChimpList).all()
+        for mclist in mclists:
+            objects.extend(self.get_all_members(mclist.id))
+        return objects
+
+    def get_all_members(self, list_id):
+        members = []
+        result = self.mailchimp.lists.members.all(list_id, get_all=True,
+                                                  # TODO: maybe should try this instead of
+                                                  # the default which seems to be 500
+                                                  # count=1000
+        )
+        members.extend(result['members'])
+        return members
+
+    def normalize_host_object(self, member):
+        last_changed = self.mailchimp_datetime(member['last_changed'])
+        return {
+            'list_id': member['list_id'],
+            'id': member['id'],
+            'email_address': member['email_address'],
+            'contact_id': member['contact_id'],
+            'full_name': member['full_name'],
+            'email_type': member['email_type'],
+            'status': member['status'],
+            # TODO: this API endpoint does not appear to include this field?
+            # 'unsubscribe_reason': member.get('unsubscribe_reason'),
+            'last_changed': make_utc(last_changed),
+            'source': member['source'],
+        }

rattail_mailchimp/importing/model.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  Rattail -- Retail Software Framework
+#  Copyright © 2010-2021 Lance Edgar
+#
+#  This file is part of Rattail.
+#
+#  Rattail is free software: you can redistribute it and/or modify it under the
+#  terms of the GNU General Public License as published by the Free Software
+#  Foundation, either version 3 of the License, or (at your option) any later
+#  version.
+#
+#  Rattail is distributed in the hope that it will be useful, but WITHOUT ANY
+#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+#  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+#  details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Rattail.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Rattail/MailChimp model importers
+"""
+
+from rattail.importing.model import ToRattail
+from rattail_mailchimp.db import model
+
+
+##############################
+# custom models
+##############################
+
+class MailChimpListImporter(ToRattail):
+    """
+    Importer for MailChimpList data
+    """
+    model_class = model.MailChimpList
+
+
+class MailChimpListMemberImporter(ToRattail):
+    """
+    Importer for MailChimpListMember data
+    """
+    model_class = model.MailChimpListMember
+
+    @property
+    def supported_fields(self):
+        return self.simple_fields + [
+            'list_id',
+        ]
+
+    def setup(self):
+        super(MailChimpListMemberImporter, self).setup()
+
+        if 'list_id' in self.fields:
+            model = self.model
+            self.mailchimp_lists = self.cache_model(model.MailChimpList,
+                                                    key='id')
+
+    def get_mailchimp_list(self, list_id):
+        if hasattr(self, 'mailchimp_lists'):
+            return self.mailchimp_lists.get(list_id)
+
+        model = self.model
+        return self.session.query(model.MailChimpList)\
+                           .filter(model.MailChimpList.id == list_id)\
+                           .first()
+
+    def normalize_local_object(self, member):
+        data = super(MailChimpListMemberImporter, self).normalize_local_object(member)
+
+        if 'list_id' in self.fields:
+            data['list_id'] = member.list.id if member.list else None
+
+        return data
+
+    def update_object(self, member, data, local_data=None):
+        member = super(MailChimpListMemberImporter, self).update_object(member, data, local_data)
+
+        if 'list_id' in self.fields:
+            list_id = data['list_id']
+            if list_id:
+                mclist = self.get_mailchimp_list(list_id)
+                assert mclist
+                member.list = mclist                    
+            elif member.list:
+                member.list = None
+
+        return member