thirteen_f 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c49261f579858881f09bf7f929b5e26ab270a3212f04d873ced78c8ff2cca5a7
-  data.tar.gz: 7357540f69f1cd5e3dd754463d362e1f8efccebf23d2a1add14d9c8a26226049
+  metadata.gz: 97448bdbcdaea2e3d0e690584c24503c7d9e65c0140441ae8afa037b6a0d96b0
+  data.tar.gz: 4aaf17e842ee4b83693d1977fc3a36036adbdc4a65a2208b44191b0dc4237373
 SHA512:
-  metadata.gz: 990cfd15c836e9337df3d364feb813a47e2fd20b7a1269cf622b564c52e296a2fbef56d91b84f7e530237ca3594290ad05c8dbd748abb30df4ab1164e5379858
-  data.tar.gz: 2f120c6e8afc60a95b8be94358e8aa3f03ee5f19e7e87a37451a44408618146d75ffff8684986b22dcbe0ab2b040c863c2e9d73b557b89f8d1d1fafdd82770d2
+  metadata.gz: eacc83d2d8aaf67caff1807e5e4368e6c954ac5f4a59758c020241b56e53d018c430b2c7874d56a2761a8da0ad288f01fcba32ff8ab60dd651a86d822f3d4759
+  data.tar.gz: 483483c8d663da64483efa03a8292308f2425e201071155c87810d715e8d54470b6fb39ca643db6b9a96f06be1a23c58815458e726017318b88b5c7821ef0812

data/README.md

@@ -1,6 +1,6 @@
 # ThirteenF
 
-A ruby interface for S.E.C. 13-F Data. There is a lot of great finance and
+A ruby interface for S.E.C. 13F Data. There is a lot of great finance and
 investing data that is available for free, but few developer tools that let
 us interact with the data outside of commercial platforms. This library
 aims to remedy a small piece of this by providing a robust API to search and
@@ -12,6 +12,11 @@ Reports. What is a 13F Report? Please visit
 This library is meant to serve a lightweight API which developers can enhance
 via a persistence layer and/or UI in their own applications.
 
+At this time, I am sure there are a number of edge cases the gem does
+not handle. Also it only imports 13F's submitted as XML files, which only goes
+back to 2013. It is a low priority for myself to robustly parse the text files
+provided before this time.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -30,7 +35,65 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Search
+
+```ruby
+search = ThirteenF::Search.new('Berkshire Hathaway')
+search = ThirteenF::Search.new('BERKSHIRE HATHAWAY INC')
+search.get_companies
+search.companies
+```
+
+### Companies
+
+```ruby
+company = search.companies.first
+company.get_filings # grabs 10 13F filings by default which is the minimum
+company.get_filings(count: 20) # can supply an optional count keyword arg to get more filings
+company.get_most_recent_holdings
+company.most_recent_holdings # returns positions from more recent 13F filing
+
+company.cik # type: String | ex: "0001067983"
+company.name # type: String | ex: "BERKSHIRE HATHAWAY INC"
+company.state_or_country # type: String | ex: "NE"
+```
+
+### Filings
+
+```ruby
+company.get_filings
+filing = company.filings.first
+filing.company
+filing.get_positions
+filing.positions # returns the US public securities held by the company at the
+                 # time of the period of the report
+
+filing.index_url # type: String
+filing.response_status # type: String | ex: "200 OK"
+filing.period_of_report # type: Date or nil
+filing.time_accepted # type: DateTime or nil
+filing.table_html_url # type: String or nil
+filing.table_xml_url # type: String or nil
+filing.cover_page_html_url # String or nil
+```
+
+### Positions
+
+```ruby
+position = filing.positions.first
+position.filing
+
+position.name_of_issuer # type: String | ex: "EBAY INC"
+position.title_of_class # type: String | ex: "COM"
+position.cusip # type: String | ex: "278642103"
+position.value_in_thousands # type: Integer | ex: 722018
+position.shares_or_principal_amount # type: Integer | ex: 19994970
+position.shares_or_principal_amount_type # type: String | ex: "SH"
+position.put_or_call # type: String or nil | ex: "PUT"
+position.investment_discretion # type: String | ex: "DFND"
+position.other_managers # type: String or nil | ex: "1,4,11"
+position.voting_authority # type: Hash | ex: { sole: 19994970, shared: 0, none: 0 }
+```
 
 ## Development
 

data/lib/thirteen_f/company.rb

@@ -37,7 +37,13 @@ class ThirteenF
     def get_most_recent_holdings
       get_filings unless filings
       most_recent_filing = filings.select(&:period_of_report).max_by(&:period_of_report)
-      @most_recent_holdings = Position.from_xml_filing most_recent_filing
+      most_recent_filing.get_positions
+      @most_recent_holdings =  most_recent_filing.positions
+      true
+    end
+
+    def get_filings(count: 10)
+      @filings = Filing.from_index_urls thirteen_f_urls(count: count), self
       true
     end
 
@@ -45,15 +51,10 @@ class ThirteenF
       "#{BASE_URL}/cgi-bin/browse-edgar?CIK=#{cik}"
     end
 
-    def thirteen_f_filings_url(count: 100)
+    def thirteen_f_filings_url(count: 10)
       "#{sec_filings_page_url}&type=13f&count=#{count}"
     end
 
-    def get_filings(count: 100)
-      @filings = Filing.from_index_urls thirteen_f_urls(count: count)
-      true
-    end
-
     private
       def self.parse_name(name_cell)
         name_cell.text.split("\n").first

data/lib/thirteen_f/filing.rb

@@ -7,23 +7,23 @@ class ThirteenF
   class Filing
     attr_reader :index_url, :table_html_url, :table_xml_url,
       :cover_page_html_url, :cover_page_xml_url, :complete_text_file_url,
-      :period_of_report, :time_accepted, :response_status
+      :period_of_report, :time_accepted, :response_status, :company, :positions
 
     BASE_URL = 'https://www.sec.gov'
 
-    def self.from_index_urls(urls)
+    def self.from_index_urls(urls, company)
       redo_count = 0
       urls.map do |index_url|
         response = HTTP.get index_url
         sleep 0.33
         if response.status == 200
           redo_count = 0
-          attributes = set_attributes(response, index_url)
+          attributes = set_attributes(response, index_url, company)
           new(**attributes)
         else
           redo_count += 1
           redo unless redo_count > 1
-          attributes = bad_response_attributes(response, index_url)
+          attributes = bad_response_attributes(response, index_url, company)
           new(**attributes)
         end
       end
@@ -42,10 +42,11 @@ class ThirteenF
       end
     end
 
-    def initialize(response_status:, index_url:, complete_text_file_url:,
-                   period_of_report:, time_accepted:, table_html_url: nil,
-                   table_xml_url: nil, cover_page_html_url: nil,
-                   cover_page_xml_url: nil)
+    def initialize(response_status:, index_url:, company:,
+                   complete_text_file_url:, period_of_report:, time_accepted:,
+                   table_html_url: nil, table_xml_url: nil,
+                   cover_page_html_url: nil, cover_page_xml_url: nil)
+      @company = company
       @response_status = response_status
       @index_url = index_url
       @table_html_url = table_html_url
@@ -58,11 +59,18 @@ class ThirteenF
       true
     end
 
+    def get_positions
+      return false unless period_of_report
+      @positions = Position.from_xml_filing self
+      true
+    end
+
     private
-      def self.set_attributes(response, index_url)
+      def self.set_attributes(response, index_url, company)
         page = Nokogiri::HTML response.to_s
         table_links = page.search('table.tableFile')[0].search('a')
         attributes = Hash.new
+        attributes[:company] = company
         attributes[:response_status] = response.status.to_s
         attributes[:index_url] = index_url
         attributes[:period_of_report] = get_period_of_report page
@@ -98,8 +106,9 @@ class ThirteenF
         attributes
       end
 
-      def self.bad_response_attributes(response, index_url)
+      def self.bad_response_attributes(response, index_url, company)
         attributes = Hash.new
+        attributes[:company] = company
         attributes[:response_status] = response.status.to_s
         attributes[:index_url] = index_url
         attributes[:period_of_report] = nil
@@ -108,12 +117,12 @@ class ThirteenF
         attributes
       end
 
-      def assign_attributes(response_status:, index_url:, complete_text_file_url:,
-                    period_of_report:, time_accepted:, table_html_url: nil,
-                    table_xml_url: nil, cover_page_html_url: nil,
-                    cover_page_xml_url: nil)
+      def assign_attributes(response_status:, index_url:, company:,
+                            complete_text_file_url:, period_of_report:,
+                            time_accepted:, table_html_url: nil, table_xml_url:
+                            nil, cover_page_html_url: nil,
+                            cover_page_xml_url: nil)
         @response_status = response_status
-        @index_url = index_url
         @table_html_url = table_html_url
         @table_xml_url = table_xml_url
         @cover_page_html_url = cover_page_html_url

data/lib/thirteen_f/position.rb

@@ -9,7 +9,7 @@ class ThirteenF
       :investment_discretion, :other_managers, :voting_authority, :filing
 
     def self.from_xml_filing(filing)
-      return unless filing.table_xml_url
+      return nil unless filing.table_xml_url
       response = HTTP.get filing.table_xml_url
       xml_doc = Nokogiri::XML response.to_s
       xml_doc.search('infoTable').map do |info_table|
@@ -27,9 +27,9 @@ class ThirteenF
       @name_of_issuer = info_table.search('nameOfIssuer').text
       @title_of_class = info_table.search('titleOfClass').text
       @cusip = info_table.search('cusip').text
-      @value_in_thousands = info_table.search('value').text
+      @value_in_thousands = to_integer(info_table.search('value').text)
       @shares_or_principal_amount_type = info_table.search('sshPrnamtType').text
-      @shares_or_principal_amount = info_table.search('sshPrnamt').text
+      @shares_or_principal_amount = to_integer(info_table.search('sshPrnamt').text)
 
       not_found = info_table.search('putCall').count == 0
       @put_or_call = info_table.search('putCall').text unless not_found
@@ -37,11 +37,16 @@ class ThirteenF
       @investment_discretion = info_table.search('investmentDiscretion').text
       @other_managers = info_table.search('otherManager').text
       @voting_authority = {
-        sole: info_table.search('Sole').text,
-        shared: info_table.search('Shared').text,
-        none: info_table.search('None').text
+        sole: to_integer(info_table.search('Sole').text),
+        shared: to_integer(info_table.search('Shared').text),
+        none: to_integer(info_table.search('None').text)
       }
     end
+
+    private
+      def to_integer(text)
+        text.delete(',').to_i
+      end
   end
 end
 

data/lib/thirteen_f/version.rb

@@ -1,3 +1,3 @@
 class ThirteenF
-  VERSION = "0.1.2"
+  VERSION = "0.2.1"
 end

data/thirteen_f.gemspec

@@ -6,13 +6,13 @@ Gem::Specification.new do |spec|
   spec.authors       = ["fordfischer"]
   spec.email         = ["fordfischer07@gmail.com"]
 
-  spec.summary       = %q{A ruby interface for S.E.C. 13-F Data.}
+  spec.summary       = %q{A ruby interface for S.E.C. 13F Data.}
 
-  spec.description   = %q{thirteen_f lets you easily interact with SEC 13-F
-  filing data in all the ways we think normal human beings might want to. The
-  SEC is the U.S. Securities and Exchange Commission. 13-F filings are
-  disclosures large institutional investors in public securites have to provide
-  and make public every quarter.}
+  spec.description   = %q{thirteen_f lets you easily search and retrieve SEC 13F
+  filing data. The SEC is the U.S. Securities and Exchange Commission. 13F
+  filings are disclosures large institutional investors in public securites have
+  to provide and make public every quarter. It is a great way to follow what
+  different investors have been doing.}
   spec.homepage      = "https://github.com/fordfischer/thirteen_f"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thirteen_f
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - fordfischer
@@ -67,11 +67,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |-
-  thirteen_f lets you easily interact with SEC 13-F
-    filing data in all the ways we think normal human beings might want to. The
-    SEC is the U.S. Securities and Exchange Commission. 13-F filings are
-    disclosures large institutional investors in public securites have to provide
-    and make public every quarter.
+  thirteen_f lets you easily search and retrieve SEC 13F
+    filing data. The SEC is the U.S. Securities and Exchange Commission. 13F
+    filings are disclosures large institutional investors in public securites have
+    to provide and make public every quarter. It is a great way to follow what
+    different investors have been doing.
 email:
 - fordfischer07@gmail.com
 executables: []
@@ -120,5 +120,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: A ruby interface for S.E.C. 13-F Data.
+summary: A ruby interface for S.E.C. 13F Data.
 test_files: []