partitioned 0.8.0 → 1.0.1

data/lib/partitioned/partitioned_base.rb

@@ -1,9 +1,10 @@
 #
 # :include: ../../README
 #
+
 module Partitioned
   #
-  # used by PartitionedBase class methods that must be overidden.
+  # Used by PartitionedBase class methods that must be overridden.
   #
   class MethodNotImplemented < StandardError
     def initialize(model, method_name, is_class_method = true)
@@ -16,11 +17,11 @@ module Partitioned
   # an ActiveRecord::Base class that can be partitioned.
   #
   # Uses a domain specific language to configure, see Partitioned::PartitionedBase::Configurator
-  # for more information
+  # for more information.
   #
-  # Extends Partitioned::BulkMethodsMixin to provide create_many and update_many
+  # Extends Partitioned::BulkMethodsMixin to provide create_many and update_many.
   #
-  # Uses PartitionManager to manage creation of child tables
+  # Uses PartitionManager to manage creation of child tables.
   #
   # Monkey patches some ActiveRecord routines to call back to this class when INSERT and UPDATE
   # statements are built (to determine the table_name with respect to values being inserted or updated)
@@ -32,69 +33,86 @@ module Partitioned
     self.abstract_class = true
 
     #
-    # returns an array of attribute names (strings) used to fetch the key value(s)
+    # Returns an array of attribute names (strings) used to fetch the key value(s)
     # the determine this specific partition table.
     #
+    # @return [String] the column name used to partition this table
+    # @return [Array<String>] the column names used to partition this table
     def self.partition_keys
       return configurator.on_fields
     end
 
     #
-    # the specific values for a partition of this active record's type which are defined by
-    # #partition_keys
+    # The specific values for a partition of this active record's type which are defined by
+    # {#self.partition_keys}
     #
+    # @param [Hash] values key/value pairs to extract values from
+    # @return [Object] value of partition key
+    # @return [Array<Object>] values of partition keys
     def self.partition_key_values(values)
       symbolized_values = values.symbolize_keys
       return self.partition_keys.map{|key| symbolized_values[key.to_sym]}
     end
 
     #
-    # the name of the current partition table determined by this active records attributes that
+    # The name of the current partition table determined by this active records attributes that
     # define the key value(s) for the constraint check.
     #
+    # @return [String] the fully qualified name of the database table, ie: foos_partitions.p17
     def partition_table_name
       symbolized_attributes = attributes.symbolize_keys
       return self.class.partition_name(*self.class.partition_keys.map{|attribute_name| symbolized_attributes[attribute_name]})
     end
 
     #
-    # normalize the value to be used for partitioning.  This allows, for instance, a class that partitions on
-    # a time field to group the times by month.  An integer field might be grouped by every 10mil values, A
+    # Normalize the value to be used for partitioning. This allows, for instance, a class that partitions on
+    # a time field to group the times by month. An integer field might be grouped by every 10mil values, A
     # string field might be grouped by its first character.
     #
+    # @param [Object] value the partition key value
+    # @return [Object] the normalized value for the key value passed in
     def self.partition_normalize_key_value(value)
       return value
     end
 
     #
-    # range generation provided for methods like created_infrastructure that need a set of partition key values
+    # Range generation provided for methods like created_infrastructure that need a set of partition key values
     # to operate on.
     #
+    # @param [Object] start_value the first value to generate the range from
+    # @param [Object] end_value the last value to generate the range from
+    # @param [Object] step (1) number of values to advance.
+    # @return [Enumerable] the range generated
     def self.partition_generate_range(start_value, end_value, step = 1)
       return Range.new(start_value, end_value).step(step)
     end
 
     #
-    # return an instance of this partition table's table manager.
+    # Return an instance of this partition table's table manager.
     #
+    # @return [{PartitionManager}] the partition manager for this partitioned model
     def self.partition_manager
       @partition_manager = self::PartitionManager.new(self) unless @partition_manager.present?
       return @partition_manager
     end
 
     #
-    # return an instance of this partition table's sql_adapter (used by the partition manage to
+    # Return an instance of this partition table's sql_adapter (used by the partition manage to
     # create SQL statements)
     #
+    # @return [{SqlAdapter}] the object used to create sql statements for this partitioned model
     def self.sql_adapter
       @sql_adapter = self::SqlAdapter.new(self) unless @sql_adapter.present?
       return @sql_adapter
     end
 
     #
-    # in activerecord 3.0 we need to supply an Arel::Table for the key value(s) used
+    # In activerecord 3.0 we need to supply an Arel::Table for the key value(s) used
     # to determine the specific child table to access.
     #
+    # @param [Hash] values key/value pairs for all attributes
+    # @param [String] as (nil) the name of the table associated with this Arel::Table
+    # @return [Arel::Table] the generated Arel::Table
     def self.dynamic_arel_table(values, as = nil)
       @arel_tables ||= {}
       key_values = self.partition_key_values(values)
@@ -106,9 +124,11 @@ module Partitioned
     end
 
     #
-    # used by our active record hacks to supply an Arel::Table given this active record's
+    # Used by our active record hacks to supply an Arel::Table given this active record's
     # current attributes.
     #
+    # @param [String] as (nil) the name of the table associated with the Arel::Table
+    # @return [Arel::Table] the generated Arel::Table
     def dynamic_arel_table(as = nil)
       symbolized_attributes = attributes.symbolize_keys
       key_values = Hash[*self.class.partition_keys.map{|name| [name,symbolized_attributes[name]]}.flatten]
@@ -118,6 +138,8 @@ module Partitioned
     # :from_partition_scope is generally not used directly,
     # use helper self.from_partition so that the derived class
     # can be passed into :from_partition_scope
+    #
+    # @return [Hash] the from scoping
     scope :from_partition_scope, lambda { |target_class, *partition_field|
       {
         :from => "#{target_class.partition_name(*partition_field)} AS #{target_class.table_name}"
@@ -125,7 +147,7 @@ module Partitioned
     }
 
     #
-    # real scope (uses #from_partition_scope).  This scope is used to target the
+    # Real scope (uses #from_partition_scope).  This scope is used to target the
     # active record find() to a specific child table and alias it to the name of the
     # parent table (so activerecord can generally work with it)
     #
@@ -139,6 +161,8 @@ module Partitioned
     # class methods is not inherited, one  must use this form (#from_partition) instead
     # of #from_partition_scope to get the most derived classes specific active record scope.
     #
+    # @param [*Array<Object>] partition_field the field values to partition on
+    # @return [Hash] the scoping
     def self.from_partition(*partition_field)
       from_partition_scope(self, *partition_field)
     end
@@ -146,6 +170,8 @@ module Partitioned
     # :from_partitioned_without_alias_scope is generally not used directly,
     # use helper self.from_partitioned_without_alias so that the derived class
     # can be passed into :from_partitioned_without_alias_scope
+    #
+    # @return [Hash] the from scoping
     scope :from_partitioned_without_alias_scope, lambda { |target_class, *partition_field|
       {
         :from => target_class.partition_name(*partition_field)
@@ -153,7 +179,7 @@ module Partitioned
     }
 
     #
-    # real scope (uses #from_partitioned_without_alias_scope). This scope is used to target the
+    # Real scope (uses #from_partitioned_without_alias_scope). This scope is used to target the
     # active record find() to a specific child table. Is probably best used in advanced
     # activerecord queries when a number of tables are involved in the query.
     #
@@ -176,13 +202,16 @@ module Partitioned
     # class methods is not inherited, one  must use this form (#from_partitioned_without_alias) instead
     # of #from_partitioned_without_alias_scope to get the most derived classes specific active record scope.
     #
+    # @param [*Array<Object>] partition_field the field values to partition on
+    # @return [Hash] the scoping
     def self.from_partitioned_without_alias(*partition_field)
       from_partitioned_without_alias_scope(self, *partition_field)
     end
 
     #
-    # return a object used to read configurator information
+    # Return a object used to read configurator information.
     #
+    # @return [{Configurator::Reader}] the configuration reader for this partitioned model
     def self.configurator
       unless @configurator
         @configurator = self::Configurator::Reader.new(self)
@@ -191,7 +220,7 @@ module Partitioned
     end
 
     #
-    # yields an object used to configure the ActiveRecord class for partitioning
+    # Yields an object used to configure the ActiveRecord class for partitioning
     # using the Configurator Domain Specific Language.
     # 
     # usage:
@@ -201,42 +230,45 @@ module Partitioned
     #     partition.foreign_key :company_id
     #   end
     #
+    # @return [{Configurator::Dsl}] the Domain Specifical Language UI manager
     def self.partitioned
       @configurator_dsl ||= self::Configurator::Dsl.new(self)
       yield @configurator_dsl
     end
 
     #
-    # returns the configurator DSL object
+    # Returns the configurator DSL object.
     #
+    # @return [{Configurator::Dsl}] the Domain Specifical Language UI manager
     def self.configurator_dsl
       return @configurator_dsl
     end
 
     partitioned do |partition|
       #
-      # the schema name to place all child tables.
+      # The schema name to place all child tables.
       #
-      # by default this will be the table name of the parent class with a suffix "_partitions".
-      # for a parent table name foos, that would be foos_partitions
+      # By default this will be the table name of the parent class with a suffix "_partitions".
+      #
+      # For a parent table name foos, that would be foos_partitions
       #
       partition.schema_name lambda {|model|
         return model.table_name + '_partitions'
       }
 
       #
-      # the table name of the table who is the direct ancestor of a child table.
+      # The table name of the table who is the direct ancestor of a child table.
       # The child table is defined by the partition key values passed in.
       #
       # By default this is just the active record's notion of the name of the class.
-      # Multi Level partitiong requires more work.
+      # Multi Level partitioning requires more work.
       #
       partition.parent_table_name lambda {|model, *partition_key_values|
         return model.table_name
       }
 
       #
-      # the schema name of the table who is the direct ancestor of a child table.
+      # The schema name of the table who is the direct ancestor of a child table.
       # The child table is defined by the partition key values passed in.
       #
       partition.parent_table_schema_name lambda {|model, *partition_key_values|
@@ -245,15 +277,15 @@ module Partitioned
       }
 
       #
-      # the prefix for a child table's name.  This is typically a letter ('p') so that
+      # The prefix for a child table's name. This is typically a letter ('p') so that
       # the base_name of the table can be a number generated programtically from
       # the partition key values.
       #
-      # for instance, a child table of the table 'foos' may be partitioned on
+      # For instance, a child table of the table 'foos' may be partitioned on
       # the column company_id whose value is 42.  specific child table would be named
       # 'foos_partitions.p42'
       #
-      # the 'p' is the name_prefix because 'foos_partitions.42' is not a valid table name
+      # The 'p' is the name_prefix because 'foos_partitions.42' is not a valid table name
       # (without quoting).
       #
       partition.name_prefix lambda {|model, *partition_key_values|
@@ -261,7 +293,7 @@ module Partitioned
       }
 
       #
-      # the child tables name without the schema name
+      # The child tables name without the schema name.
       #
       partition.part_name lambda {|model, *partition_key_values|
         configurator = model.configurator
@@ -269,7 +301,7 @@ module Partitioned
       }
 
       #
-      # the full name of a child table defined by the partition key values
+      # The full name of a child table defined by the partition key values.
       #
       partition.table_name lambda {|model, *partition_key_values|
         configurator = model.configurator
@@ -277,78 +309,117 @@ module Partitioned
       }
 
       #
-      # the name of the child table without a schema name or prefix. this is used to
+      # The name of the child table without a schema name or prefix. this is used to
       # build child table names for multi-level partitions.
       #
-      # for a table named foos_partitions.p42, this would be "42"
+      # For a table named foos_partitions.p42, this would be "42"
       #
       partition.base_name lambda { |model, *partition_key_values|
         return model.partition_normalize_key_value(*partition_key_values).to_s
       }
     end
 
+    #
+    # this methods are hand delegated because forwardable module conflicts
+    # with rails delegate.
+    #
+
     ##
     # :singleton-method: drop_partition_table
     # delegated to Partitioned::PartitionedBase::PartitionManager#drop_partition_table
+    def self.drop_partition_table(*partition_key_values)
+      partition_manager.drop_partition_table(*partition_key_values)
+    end
 
     ##
     # :singleton-method: create_partition_table
     # delegated to Partitioned::PartitionedBase::PartitionManager#create_partition_table
+    def self.create_partition_table(*partition_key_values)
+      partition_manager.create_partition_table(*partition_key_values)
+    end
 
     ##
     # :singleton-method: add_partition_table_index
     # delegated to Partitioned::PartitionedBase::PartitionManager#add_partition_table_index
+    def self.add_partition_table_index(*partition_key_values)
+      partition_manager.add_partition_table_index(*partition_key_values)
+    end
 
     ##
     # :singleton-method: add_references_to_partition_table
     # delegated to Partitioned::PartitionedBase::PartitionManager#add_references_to_partition_table
+    def self.add_references_to_partition_table(*partition_key_values)
+      partition_manager.add_references_to_partition_table(*partition_key_values)
+    end
 
     ##
     # :method: create_partition_schema
     # delegated to Partitioned::PartitionedBase::PartitionManager#create_partition_schema
+    def self.create_partition_schema(*partition_key_values)
+      partition_manager.create_partition_schema(*partition_key_values)
+    end
 
     ##
     # :singleton-method: add_parent_table_rules
     # delegated to Partitioned::PartitionedBase::PartitionManager#add_parent_table_rules
+    def self.add_parent_table_rules(*partition_key_values)
+      partition_manager.add_parent_table_rules(*partition_key_values)
+    end
 
     ##
     # :method: drop_old_partitions
     # delegated to Partitioned::PartitionedBase::PartitionManager#drop_old_partitions
+    def self.drop_old_partitions
+      partition_manager.drop_old_partitions
+    end
 
     ##
     # :method: create_new_partitions
     # delegated to Partitioned::PartitionedBase::PartitionManager#create_new_partitions
+    def self.create_new_partitions
+      partition_manager.create_new_partitions
+    end
 
     ##
     # :method: drop_old_partition
     # delegated to Partitioned::PartitionedBase::PartitionManager#drop_old_partition
+    def self.drop_old_partition(*partition_key_values)
+      partition_manager.drop_old_partition(*partition_key_values)
+    end
 
     ##
     # :method: create_new_partition
     # delegated to Partitioned::PartitionedBase::PartitionManager#create_new_partition
+    def self.create_new_partition(*partition_key_values)
+      partition_manager.create_new_partition(*partition_key_values)
+    end
 
     ##
     # :method: create_new_partition_tables
     # delegated to Partitioned::PartitionedBase::PartitionManager#create_new_partition_tables
+    def self.create_new_partition_tables(enumerable)
+      partition_manager.create_new_partition_tables(enumerable)
+    end
 
     ##
     # :method: create_infrastructure
     # delegated to Partitioned::PartitionedBase::PartitionManager#create_infrastructure
+    def self.create_infrastructure
+      partition_manager.create_infrastructure
+    end
 
     ##
     # :method: partition_table_name
     # delegated to Partitioned::PartitionedBase::PartitionManager#partition_table_name
+    def self.partition_table_name(*partition_key_values)
+      return partition_manager.partition_table_name(*partition_key_values)
+    end
 
     ##
     # :method: partition_name
     # delegated to Partitioned::PartitionedBase::PartitionManager#partition_table_name
-
-    extend SingleForwardable
-    def_delegators :partition_manager, :drop_partition_table, :create_partition_table,
-      :add_partition_table_index, :add_references_to_partition_table,
-      :create_partition_schema, :add_parent_table_rules, :drop_old_partitions,
-      :create_new_partitions, :drop_old_partition, :create_new_partition,
-      :create_new_partition_tables, :create_infrastructure, :partition_table_name
-    def_delegator :partition_manager, :partition_table_name, :partition_name
+    def self.partition_name(*partition_key_values)
+      return partition_manager.partition_table_name(*partition_key_values)
+    end
   end
 end

data/lib/partitioned/version.rb

@@ -1,3 +1,4 @@
 module Partitioned
-  VERSION = "0.8.0"
+  # the current version of this gem
+  VERSION = "1.0.1"
 end

data/partitioned.gemspec

@@ -6,15 +6,16 @@ require "partitioned/version"
 Gem::Specification.new do |s|
  s.name        = 'partitioned'
  s.version     = Partitioned::VERSION
+ s.license     = 'New BSD License'
  s.date        = '2012-03-07'
  s.summary     = "Postgres table partitioning support for ActiveRecord."
- s.description = "A gem providing support for table partitioning in ActiveRecord.  Support is currently only supported for postgres database.  Other features include child table management (creation and deletion) abd bulk data creating and updating"
+ s.description = "A gem providing support for table partitioning in ActiveRecord. Support is only available for postgres databases. Other features include child table management (creation and deletion) and bulk data creating and updating."
  s.authors     = ["Keith Gabryelski", "Aleksandr Dembskiy"]
  s.email       = 'keith@fiksu.com'
  s.files       = `git ls-files`.split("\n")
  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
  s.require_path = 'lib'
- s.homepage    = 'http://www.fiksu.com'
+ s.homepage    = 'http://github.com/fiksu/partitioned'
  s.add_dependency('pg')
  s.add_dependency "rails", '>= 3.0.0'
  s.add_dependency('rspec-rails')

metadata

@@ -1,76 +1,73 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: partitioned
-version: !ruby/object:Gem::Version 
-  hash: 63
+version: !ruby/object:Gem::Version
+  version: 1.0.1
   prerelease: 
-  segments: 
-  - 0
-  - 8
-  - 0
-  version: 0.8.0
 platform: ruby
-authors: 
+authors:
 - Keith Gabryelski
 - Aleksandr Dembskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-03-07 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: pg
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rails
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 3
-        - 0
-        - 0
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 3.0.0
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rspec-rails
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id003
-description: A gem providing support for table partitioning in ActiveRecord.  Support is currently only supported for postgres database.  Other features include child table management (creation and deletion) abd bulk data creating and updating
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem providing support for table partitioning in ActiveRecord. Support
+  is only available for postgres databases. Other features include child table management
+  (creation and deletion) and bulk data creating and updating.
 email: keith@fiksu.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - Gemfile
 - LICENSE
 - PARTITIONING_EXPLAINED.txt
@@ -165,40 +162,38 @@ files:
 - spec/support/shared_example_spec_helper_for_integer_key.rb
 - spec/support/shared_example_spec_helper_for_time_key.rb
 - spec/support/tables_spec_helper.rb
-homepage: http://www.fiksu.com
-licenses: []
-
+homepage: http://github.com/fiksu/partitioned
+licenses:
+- New BSD License
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: -2034428678854769428
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: -2034428678854769428
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.21
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Postgres table partitioning support for ActiveRecord.
-test_files: 
+test_files:
 - spec/dummy/.rspec
 - spec/dummy/README.rdoc
 - spec/dummy/Rakefile